clearotron 0.3.0-beta.1 → 0.3.0-beta.2

package/driver/updater-identity.mjs

@@ -0,0 +1,178 @@
+// 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
+// updater-identity.mjs — WHICH COPY OF THE UPDATER IS ACTUALLY DEPLOYING THIS BOX.
+//
+// Deploy health attributes a service to a commit by resolving a tree from the unit's WorkingDirectory
+// and from `/proc/<pid>/cmdline`. Both halves fail for exactly one unit, and it is the one that does the
+// deploying: the updater is a `oneshot` that runs from a home directory with no checkout under it, and
+// its command line is the update script rather than the product entry point. So the unit that places
+// every commit on this box was the one unit the check reported as "could NOT be read and was NOT
+// compared" — an updater running from a stale copy would place a stale tree, and nothing would notice.
+//
+// THE UPDATER STAMPS ITSELF, the way the drainer already does, and this reads that stamp. The two shapes
+// are deliberately the same: a best-effort write at the top of a tick, a verdict at the reading end, and
+// an absent stamp treated as a failure rather than a skip.
+//
+// AN ABSENT STAMP IS THE LOUD CASE, and that is the whole point rather than a severity preference. The
+// stamp writer shipped in the updater itself, so a copy of the updater old enough to predate it writes
+// no stamp at all — which is precisely "the updater is running from a stale copy", the condition this
+// exists to catch. Recording that as "not probed" would pass the exact box the check is for.
+//
+// WHAT THE SHA PAIR PROVES, AND WHAT IT DOES NOT. The stamp records the running copy's digest and the
+// digest of the master it was taken from, and those two agreeing means the running copy matches the
+// master AS THAT BOX CAN SEE IT. The master is read from a local store that nothing pulls
+// automatically, so a store nobody has fetched leaves both sides equally old and equally in agreement.
+// That case is real and this reader cannot see it; the pass message says so rather than claiming the
+// updater is current, and the updater's own tick reports the store's age on the line above.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const UPDATER_STAMP_BASENAME = "_updater-identity.json";
+
+/**
+ * Where the updater stamps itself: beside the update script, in the deploy directory it runs from.
+ *
+ * NEVER A HARDCODED PATH. The obvious spelling here is the service account's own home, and it is wrong
+ * twice over: it publishes a login on a public surface, and it disagrees with any box that points the
+ * updater somewhere else — which would red a healthy deployment forever, for a reason no message names.
+ * The caller passes the directory it derived from the unit itself, and the environment overrides both.
+ */
+export function updaterStampPath(deployDir) { return join(deployDir, UPDATER_STAMP_BASENAME); }
+
+/**
+ * The one path the reader and the writer both resolve, from the one name the writer already honours.
+ *
+ * THE READER MUST NOT INVENT A SECOND ENV NAME. A reader-only variable is a seam: a box that redirects
+ * its updater sets the writer's name, the reader keeps looking at the default, finds nothing, and
+ * reports "no stamp" — the loud branch — about a deployment that is stamping correctly. One name, read
+ * as the writer writes it: a FULL PATH to the stamp file, not a directory.
+ *
+ * @param {string|null} deployDir  where the updater runs, derived from the unit; used only as fallback
+ * @param {object} [env]           process.env, injectable so a test can drive both branches
+ */
+export function resolveUpdaterStampPath(deployDir, env = process.env) {
+  const named = env?.CLEAROTRON_UPDATER_STAMP || null;
+  if (named) return named;
+  return deployDir ? updaterStampPath(deployDir) : null;
+}
+
+/**
+ * PURE. Why this box has no updater to judge, or null when it has one.
+ *
+ * A box with no updater unit (production today, and any install that nothing keeps current) answers
+ * `systemctl show` for it with `LoadState=not-found`, an empty WorkingDirectory and no process, and it
+ * arrives as an idle row. Judging that row fails on "where it stamps could not be resolved", a red that
+ * nothing on that box can clear. So an absent unit is a skip that says why, unless the environment
+ * redirects the stamp, which says an updater exists somewhere and is to be judged. No row at all is a
+ * could-not-look, and is left to the check that says so.
+ *
+ * @param {object|undefined} row  the updater's row from the unit probe
+ * @param {object} [env]          process.env, injectable so a test can drive the redirect
+ */
+export function updaterAbsentHere(row, env = process.env) {
+  if (!row || row.load !== "not-found") return null;
+  if (resolveUpdaterStampPath(null, env)) return null;
+  return "this box has no updater unit, so nothing deploys it on a schedule and there is no running copy to compare — NOT PROBED";
+}
+
+/** The stamp, or null when there is none to read. A parse failure is a null — the verdict says so. */
+export function readUpdaterStamp(deployDir, { read = null, env = process.env } = {}) {
+  const rd = read ?? ((p) => readFileSync(p, "utf8"));
+  const path = resolveUpdaterStampPath(deployDir, env);
+  if (!path) return null;
+  try { return JSON.parse(rd(path)); } catch { return null; }
+}
+
+/** Eight characters is enough to name a commit in a message, and null stays visibly null. */
+const short = (c) => (c ? String(c).slice(0, 8) : "(unknown)");
+
+/**
+ * PURE. What deploy health should say about the copy of the updater that is deploying this box.
+ *
+ * @param {object} o
+ * @param {object|null} o.stamp        readUpdaterStamp()'s answer
+ * @param {number|null} o.now          epoch seconds, for the stamp's age
+ * @param {string|null} o.deployClone  the git toplevel this deploy is checking
+ * @param {number} [o.maxAgeSeconds]   how old a stamp may be before the updater counts as not running
+ * @returns {{state:"pass"|"fail", message:string}}
+ *
+ * THE ALLOWANCE IS THREE HOURS AGAINST AN HOURLY TICK, and it is a judgement rather than a measurement,
+ * so it is written down with its reasoning. The stamp is written at the top of every run, so on the
+ * cadence the deployment keeps, one missed tick is an hour. It is not one hour here because a tick can
+ * legitimately defer — the updater exits early while a clearance is queued, claimed or in flight — and
+ * an arm that fired on a single deferral would red a box that is busy rather than broken. Three hours
+ * is two consecutive misses: past any single deferral, and still inside the window where somebody would
+ * want to know. Six hours was the first number written and it is five missed ticks, most of a working
+ * day, which is slack a one-hour cadence does not need.
+ */
+export function updaterVerdict({ stamp, now = null, deployClone = null, maxAgeSeconds = 3 * 3600 } = {}) {
+  if (!stamp) {
+    return { state: "fail", message:
+      `no updater identity stamp at ${UPDATER_STAMP_BASENAME}: the copy of the updater that deploys this `
+      + "box did NOT say what it is, so whether it is the current one was not established. A copy old "
+      + "enough to predate the stamp writes none, which is itself the stale-updater case. This is a "
+      + "failure to look, never a pass." };
+  }
+
+  // — AN UNREADABLE SIDE IS NOT A MISMATCH. A digest that could not be taken arrives as null, and
+  // calling that "the two differ" would report drift invented out of a failure to read.
+  const wsha = stamp.wrapperSha256 ?? null;
+  const msha = stamp.masterSha256 ?? null;
+  if (!wsha || !msha) {
+    // The clause is written out per case rather than interpolated into one sentence: the single-sided
+    // wording needs the negation and the both-sided wording carries it in "neither", so the one shared
+    // sentence read "the master could be read as a digest" — the opposite of what happened, past an arm
+    // that matched the phrase and never read the verb.
+    const which = !wsha && !msha ? "neither the running copy of the updater nor its master could be read as a digest"
+      : !wsha ? "the running copy of the updater could NOT be read as a digest"
+      : "the master could NOT be read as a digest";
+    const why = stamp.masterCommitError ? ` The updater reported: ${stamp.masterCommitError}` : "";
+    return { state: "fail", message:
+      `the updater stamp is present but ${which}, so the running copy was NOT `
+      + `compared against its master.${why} This is a failure to look, never a pass.` };
+  }
+
+  // — THE AGE IS ALWAYS PRINTED AND RARELY JUDGED. A stopped deploy timer already fails on its own arm,
+  // and a second red for one condition teaches a reader to discount both. This fires only when the stamp
+  // is old enough that the updater cannot be running on any schedule the box could be keeping.
+  const writtenAt = Number(stamp.writtenAt) || 0;
+  const ageSeconds = now && writtenAt ? Math.max(0, now - writtenAt) : null;
+  const ageNote = ageSeconds === null
+    ? " (the stamp carries no readable time, so its age is unknown)"
+    : ` (stamped ${Math.floor(ageSeconds / 60)} min ago)`;
+
+  if (wsha !== msha) {
+    return { state: "fail", message:
+      `the running copy of the updater DIFFERS from its master${ageNote}: the copy that ran digests `
+      + `${short(wsha)} and the master it was taken from digests ${short(msha)}. This box is being `
+      + "deployed by an updater that is not the one in the store — reported, not reconciled." };
+  }
+
+  if (ageSeconds !== null && ageSeconds > maxAgeSeconds) {
+    return { state: "fail", message:
+      `the updater last stamped itself ${Math.floor(ageSeconds / 3600)}h ago${
+        maxAgeSeconds ? `, past the ${Math.floor(maxAgeSeconds / 3600)}h this check allows` : ""}. `
+      + "The stamp is written at the top of every tick, so a stamp this old means the updater has not "
+      + "run — whatever the box is serving, it is not tracking the branch." };
+  }
+
+  // — IS THIS UPDATER DEPLOYING THE TREE BEING CHECKED? The stamp records the checkout it places
+  // commits into. A box whose health check reads one clone while its updater feeds another is the
+  // two-clone straddle with the deploying mechanism on the far side of it, and the digests above agree
+  // in that state exactly as they do in a healthy one.
+  const norm = (p) => String(p ?? "").replace(/\/+$/, "");
+  if (deployClone && stamp.checkout && norm(stamp.checkout) !== norm(deployClone)) {
+    return { state: "fail", message:
+      `the updater matches its master${ageNote}, but it deploys a DIFFERENT tree than the one being `
+      + `checked: it places commits into ${stamp.checkout} while this check reads ${deployClone}. `
+      + "Whatever it keeps current, it is not this one." };
+  }
+
+  const into = stamp.checkout ? `, into ${stamp.checkout}` : "";
+  return { state: "pass", message:
+    `the running copy of the updater matches its master${ageNote}${into}, both digesting ${short(wsha)}`
+    + `, master read at commit ${short(stamp.masterCommit)}. This says the running copy matches the `
+    + "master AS THIS BOX HOLDS IT: the store it is read from is not pulled automatically, so a store "
+    + "nobody has fetched leaves both sides equally old and equally in agreement." };
+}

package/driver/usage-ledger.mjs

@@ -22,12 +22,12 @@ import { readFileSync, readdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { isLiveQueueMarker } from "./queue-markers.mjs";   // the wall's live-state vocabulary, not a fourth copy
 
-// The daily allowance a brand owner gets when its profile names no runCaps. Declared here rather
-// than imported from runner.mjs: a request path must not pull the runner (and its queue/dispatch
-// machinery) in. A test pins the two constants to the same value so they cannot drift apart.
+// The daily allowance a brand owner gets when its profile names no runCaps. THE ONE DECLARATION, here in
+// the leaf because a request path must not pull the runner (and its queue/dispatch machinery) in;
+// runner.mjs imports it from here. There used to be a second, held equal by a test, and the screen that
+// advertises the allowance and the gate that enforces it now cannot disagree by construction.
 //
-// THIS ONE IS THE ADVERTISER AND runner.mjs IS THE ENFORCER, so they move together or the screen promises
-// what the gate refuses. raised both from the beta's 2 to 20.
+// Raised from the beta's 2 to 20.
 export const DEFAULT_CLIENT_DAILY_RUNS = 20;
 
 /**

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,11 @@
 # trademark-artifacts-mcp
 
+## 0.3.0-beta.2
+
+### Patch Changes
+
+- eacfce4: Fixed: An assistant reading a knockout's filings through the connector now gets each filing's page at the trade mark office, as the report does. Where that register publishes no page for a single record, it gets the office and the number instead. Before, it got a reference that opens nowhere.
+
 ## 0.3.0-beta.1
 
 ### Patch Changes

package/mcp-server/http-server.mjs

@@ -259,22 +259,25 @@ if (isMain) {
   // are useful without it, and failing closed here would turn a config slip into an outage.
   try {
     const { loadProfiles } = await import("../driver/profiles.mjs");
-    const roster = [...loadProfiles({ force: true }).keys()].sort();
+    const profiles = loadProfiles({ force: true });
+    const roster = [...profiles.keys()].sort();
     const where = envFrom(process.env, "CLEAROTRON_CUSTOMERS_DIR") || "(unset — BUNDLED demo roster at driver/profiles)";
     log(`roster: ${roster.length} customer(s) from ${where} — [${roster.join(", ")}]`);
-    if (!envFrom(process.env, "CLEAROTRON_CUSTOMERS_DIR")) {
-      // — SAME FACT, DIFFERENT READER. "Every real customer will be refused" is
-      // true and useless to a demo visitor, who has none and wants none; what a first-time reader needs
-      // is what the demo IS. Composed once, in driver/demo-posture.mjs, because the other mis-aimed
-      // warning of this pair lives in the portal process and the two must not answer differently.
-      //
-      // OUTSIDE A DEMO IT IS UNCHANGED AND STILL A WARNING — an operator whose roster is the bundled one
-      // has a real deployment that will refuse every real customer.
-      const posture = demoPostureLine(process.env);
-      if (posture) log(posture);
-      else log(`WARNING: CLEAROTRON_CUSTOMERS_DIR is unset, so start_run is validating against the BUNDLED demo roster.`
+    // — SAME FACT, DIFFERENT READER. "Every real customer will be refused" is
+    // true and useless to a demo visitor, who has none and wants none; what a first-time reader needs
+    // is what the demo IS. Composed once, in driver/demo-posture.mjs, because the other mis-aimed
+    // warning of this pair lives in the portal process and the two must not answer differently.
+    //
+    // ASKED BEFORE THE STORE IS. A demo runs on a store of its own under its base, so an unset store no
+    // longer tells a demo from an operator's install. The line is composed from the roster read above.
+    //
+    // OUTSIDE A DEMO IT IS UNCHANGED AND STILL A WARNING — an operator whose roster is the bundled one
+    // has a real deployment that will refuse every real customer.
+    const posture = demoPostureLine(process.env, { roster: profiles });
+    if (posture) log(posture);
+    else if (!envFrom(process.env, "CLEAROTRON_CUSTOMERS_DIR"))
+      log(`WARNING: CLEAROTRON_CUSTOMERS_DIR is unset, so start_run is validating against the BUNDLED demo roster.`
         + " Every real customer will be refused with \"names no known customer\". Set it to the config store's profiles directory.");
-    }
     const granted = grantedAccounts(envFrom(process.env, "CLEAROTRON_ACCESS_FILE"));
     const missing = granted.filter((a) => !roster.includes(a));
     if (missing.length) {

package/mcp-server/lib/driver.mjs

@@ -20,6 +20,13 @@ export {
 // exists: a second copy of a path table drifts, and the drift shows up as an artifact reported missing.
 export { koPaths } from "../../driver/stages-knockout.mjs";
 
+// HOW PUBLISH ADDRESSES A KNOCKOUT'S LISTED FILINGS. On a register with no record pages of its own, each
+// filing with an office number is given the office's own page, or the office and the number and why that is
+// not a link, and the report, the workbook and report-data.json state it. The evidence view states it from
+// this same function rather than from a second reading of the numbers. office-record-links.mjs imports
+// nothing, so the read-only server stays light.
+export { addressListedFilings } from "../../driver/publish/office-record-links.mjs";
+
 // stripInternal/stripEngineInternals/stripTelemetry are the driver's OWN client-safety transforms — the
 // same ones publish/render.mjs applies to the client HTML export. lib/scrub.mjs composes them so the MCP
 // client surface and the delivered report answer "what may a client see?" from ONE definition ( R1:

package/mcp-server/lib/knockout.mjs

@@ -27,7 +27,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { basename, join } from "node:path";
 
-import { koPaths } from "./driver.mjs";
+import { koPaths, addressListedFilings } from "./driver.mjs";
 import { driverDir } from "../../shared/driver-dir.mjs";
 
 const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
@@ -207,14 +207,26 @@ const knockoutNegatives = (doc) => marksOf(doc).flatMap((m) =>
 export function knockoutEvidence(run) {
   const doc = knockoutDoc(run);
   const recordsDoc = readJson(koPaths(run.runDir).registerRecords);
+  // EACH FILING ADDRESSED AS PUBLISH ADDRESSES IT, keyed on the sidecar's own register. On a register with
+  // no record pages of its own, the listing's link is the engine's handle, `/mark/<office>/<id>`, which a
+  // reader can open nowhere, and the report never shows it for a filing with an office number: it gives the
+  // office's own page, or the office and the number and why that is not a link. This view states the same,
+  // from the same function over the same sidecar, so the connector and the report cannot give one filing
+  // two links. On any other register the call sets nothing, and every row is exactly as it was.
+  if (Array.isArray(recordsDoc?.marks)) addressListedFilings(recordsDoc);
   const out = [];
 
   for (const entry of (Array.isArray(recordsDoc?.marks) ? recordsDoc.marks : [])) {
     for (const r of (Array.isArray(entry.records) ? entry.records : [])) {
+      // report-data.json's own field for the same filing, in its shape.
+      const office = r.officeLink ? { label: r.officeLink.label, href: r.officeLink.href, reason: r.officeLink.reason } : null;
       out.push({
         layer: "register", mark: r.mark ?? entry.name ?? null, owner: r.owner ?? null,
         country: r.territory ?? null, classes: r.classes ?? [], status: r.status ?? null,
-        url: r.url ?? null, recordId: r.recordId ?? null,
+        // The source link: the office's page where the filing has one, none where it is cited by number,
+        // and the listing's own link only for a filing publish did not address.
+        url: office ? office.href : (r.url ?? null), recordId: r.recordId ?? null,
+        ...(office ? { officeRecord: office } : {}),
         matchedForm: r.matchedForm ?? null, matchedBasis: r.matchedBasis ?? null,
         // `retrieved` is what the provider actually returned for this row, and it is a FACT about the
         // fetch rather than about the filing. A reader deciding how much weight to give a row needs it.

package/mcp-server/lib/ops.mjs

@@ -19,7 +19,8 @@ import { probeQueueWatch, unwatchedQueueWarning } from "../../driver/queue-watch
 import { resolveRun, runAccountKey } from "./runs.mjs";
 import { assertAccountAccess, attributionOf } from "../../shared/scope.mjs";
 import { requestCancel, isCancelled } from "../../driver/cancel.mjs";   // one marker shape, shared with the engine
-import { readEngineChild, engineChildIsLive } from "../../driver/engine/child-record.mjs";   //
+import { readEngineChild, engineChildIsLive, endEngineChild } from "../../driver/engine/child-record.mjs";   //
+import { killEscalateMs } from "../../driver/engine/common.mjs";   // the watchdogs' grace, reused by an immediate stop
 import { stopReason } from "../../shared/stop-reason.mjs";   //
 import { envFrom } from "../../shared/env-aliases.mjs";   // — resolves EITHER spelling; names the retired one because that is the live-writable half
 
@@ -290,9 +291,11 @@ export function startRun(args = {}, { scope } = {}) {
 }
 
 // stop_run — cancel. A not-yet-claimed queue job is removed (a REAL cancel before any spend). A running run
-// gets a .cancel sentinel + honest status (in-flight turns are not force-killed from here). id cancels by
-// queue id; runId cancels a started run.
-export function stopRun(args = {}, { scope } = {}) {
+// gets a .cancel sentinel + honest status; its turn in flight is ended from here only when `immediate` asks
+// for that. id cancels by queue id; runId cancels a started run.
+//
+// `endTurn` is what ends that turn. The dispatch passes `{ scope }` alone, so only a test reaches it.
+export async function stopRun(args = {}, { scope, endTurn = endEngineChild } = {}) {
   const agent = args.agent ? String(args.agent) : "";
   if (args.id) {
     const qdir = queueDir(agent);
@@ -384,14 +387,27 @@ export function stopRun(args = {}, { scope } = {}) {
         // kills a stranger. This is acceptance 5's already-exited case.
         immediate = { attempted: false, why: "the recorded engine turn has already exited — the cancel stands", pid: child.pid };
       } else {
-        try {
-          process.kill(child.pid, "SIGTERM");
-          immediate = { attempted: true, signalled: "SIGTERM", pid: child.pid };
-        } catch (e) {
+        // SIGNALLED IS NOT ENDED, so the answer waits to see. `endTurn` sends SIGTERM to the turn — to its
+        // whole process group when the record names the group's leader, which both engines' detached
+        // spawns make it — watches until nothing of it is left, and sends SIGKILL to whatever remains
+        // when the grace runs out. `ended` is what it SAW, and the sentences below are written from that
+        // field alone: `process.kill` returning says only that the OS accepted the signal for delivery.
+        //
+        // Measured on the owner's WSL install of 0.3.0-beta.1: this branch answered "the step in flight
+        // has been ended ... terminal in seconds", read off the signal alone, and the run stopped at the
+        // next step boundary.
+        //
+        // The portal waits 30 seconds for this answer, and this waits for the turn before answering: the
+        // grace, then up to two seconds after a SIGKILL. The cap keeps a long grace set for the watchdogs
+        // from outlasting the portal's wait.
+        const took = await endTurn(child, { graceMs: Math.min(killEscalateMs(), 10000) });
+        immediate = took?.signalled
+          ? { attempted: true, signalled: took.signalled, escalated: took.escalated ?? null, group: took.group === true,
+              pid: child.pid, ended: took.ended === true,
+              ...(took.ended === true ? {} : { why: "the step in flight was told to stop and had not ended when it was last checked" }) }
           // ESRCH — it died between the liveness read and the signal, which is a race we lose harmlessly.
           // EPERM — it is not ours to signal, which is a real finding and must not read as success.
-          immediate = { attempted: true, signalled: null, pid: child.pid, error: e?.code ?? String(e?.message ?? e) };
-        }
+          : { attempted: true, signalled: null, pid: child.pid, error: took?.error ?? "no signal was sent" };
       }
     }
 
@@ -443,18 +459,24 @@ export function stopRun(args = {}, { scope } = {}) {
     // distinguish them is the state the owner already told us says nothing. A pressed-immediate that
     // could not find a turn to end is reported as the boundary stop it actually became; presenting it
     // as an immediate stop would be the second silent thing in a row on the same control.
+    //
+    // AND IT SAYS "ENDED" ONLY FROM `ended`, which is what the stop saw. A turn that was told to stop and
+    // was still there afterwards is reported as the boundary stop it became.
+    const fellBack = immediate?.why ?? immediate?.error ?? "the step in flight could not be ended";
     if (alreadyStopping) {
       return { ok: true, action: "already-stopping", runId: run.runId, requestedAt: rec?.ts ?? null, immediate,
-        note: immediate?.attempted
-          ? `Already stopping — the request was filed at ${rec?.ts ?? "an earlier press"}, and the step in flight has now been ended. The run goes terminal in seconds.`
-          : `Already stopping — the request was filed at ${rec?.ts ?? "an earlier press"} and the step in flight is being allowed to finish. Pressing again changes nothing.` };
+        note: immediate?.ended === true
+          ? `Already stopping — the request was filed at ${rec?.ts ?? "an earlier press"}, and the step in flight has now ended. Nothing will be delivered.`
+          : immediate?.attempted
+            ? `Already stopping — the request was filed at ${rec?.ts ?? "an earlier press"}. An immediate stop was asked for and could not be made: ${fellBack}. The run ends at its next step boundary.`
+            : `Already stopping — the request was filed at ${rec?.ts ?? "an earlier press"} and the step in flight is being allowed to finish. Pressing again changes nothing.` };
     }
-    if (immediate?.attempted && immediate.signalled)
+    if (immediate?.ended === true)
       return { ok: true, action: "cancel-requested", runId: run.runId, requestedAt: rec?.ts ?? null, immediate,
-        note: "Stopping now. The step in flight has been ended rather than allowed to finish, so the run goes terminal in seconds. What that step had already spent is spent, and everything recorded before it is kept." };
+        note: "Stopping now. The step in flight has ended: what it had already spent is spent, everything recorded before it is kept, and nothing will be delivered." };
     if (args.immediate === true)
       return { ok: true, action: "cancel-requested", runId: run.runId, requestedAt: rec?.ts ?? null, immediate,
-        note: `Stopping at the next step boundary. An immediate stop was asked for and could not be made: ${immediate?.why ?? immediate?.error ?? "the step in flight could not be ended"}. A step already under way finishes first. Nothing will be delivered.` };
+        note: `Stopping at the next step boundary. An immediate stop was asked for and could not be made: ${fellBack}. A step already under way finishes first. Nothing will be delivered.` };
     return { ok: true, action: "cancel-requested", runId: run.runId, requestedAt: rec?.ts ?? null,
       note: "Stopping. The run ends at its next step boundary; a step already under way finishes first, and what it has already spent is spent. Nothing will be delivered." };
   }

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.2",
   "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.",
@@ -17,6 +17,6 @@
     "jose": "^6.2.3"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   }
 }

package/mcp-server/server.mjs

@@ -594,7 +594,7 @@ const TOOL_DEFS = [
   { name: "plan_run", description: "FREE PREVIEW — resolve what a search WOULD do and return it, spending nothing and queueing nothing. Takes the SAME arguments as start_run. Use this BEFORE start_run whenever the requester has not already confirmed the specifics: it reports the PRODUCT that resolves and WHERE it came from (their request, the account default, a saved search, or the territories themselves), the territories and marketplaces that would ACTUALLY be searched, the turnaround, and any blockers as questions to put back. Show the result to the requester; then call start_run with the SAME arguments to actually run it. Nothing here reserves or holds anything.", inputSchema: { type: "object", properties: { markName: { type: "string", description: "The mark (single-mark form). REQUIRED unless marks[] is given." }, marks: { type: "array", items: { type: "object", properties: { name: { type: "string" }, classes: { type: "array", items: { type: "number" } }, ref: { type: "string" } }, required: ["name"] } }, classes: { type: "array", items: { type: "number" } }, goods: { type: "string" }, jurisdictions: { type: "array", items: { type: "string" } }, platforms: { type: "array", items: { type: "string" } }, customer: { type: "string" }, profileKey: { type: "string", description: "The customer ACCOUNT key (see list_profiles). REQUIRED for an accounts-scoped session (your grant names the keys — see describe_options)." }, projectKey: { type: "string" }, forwarder: { type: "string", description: "Requester/reply-routing key — same as start_run, so the preview describes the job that would actually be built. Account sessions may omit it — it is stamped from your verified identity." }, forwarderEmail: { type: "string" }, ref: { type: "string" }, product: { type: "string", enum: ORDERABLE_PRODUCTS, description: PRODUCT_DESC }, nativeLanguage: { type: "boolean", description: "OPTIONAL, and only on a multi-country-focus-search: the native-language investigation. Send TRUE or omit the field — FALSE IS REFUSED, not honoured: the toggle only ever added, so there is nothing for false to switch off, and accepting it would let you believe you had removed a reading that runs anyway. It runs AUTOMATICALLY on a full-country-search and is not part of the other two, so asking for it there is refused rather than accepted and ignored. It routes on territory — the scope must name one it covers." }, worldwide: { type: "boolean", description: "Search EVERYWHERE, and refuse to be narrowed by the account's own default territories. This is not the same as omitting jurisdictions, which means \"whatever the account says\" — the two used to be indistinguishable on this wire, which is how a request that bought everywhere ran an account's seven countries. Never send \"Worldwide\" as a jurisdictions entry." }, recipeKey: { type: "string" }, upfrontInstructions: { type: "string" }, deadline: { type: "string" }, deliveryRoute: { type: "string", enum: ["email", "portal"], description: "OPTIONAL: how the delivered packet leaves — email (default). \"portal\" is reserved for the portal delivery lane and CLARIFIES at admission until it ships (never a silent no-op) — so the preview BLOCKS it here rather than describing a job start_run could not run." }, commercialFlexibility: { type: "string" }, priorUse: { type: "string" }, campaignShape: { type: "string", description: "Campaign-shape FACTS from the request/client — how the mark will be deployed: standalone brand vs flavour/sub-brand under a NAMED house mark; seasonal/limited vs permanent; launch scale. Verbatim facts only — the engine records them on the matter frame instead of inferring a launch shape." }, customerUnknown: { type: "boolean" } }, required: ["forwarder"] } },
   // ---- OPS write-face (requires an ops token; never exposed to a user/internal session) ----
   { name: "start_run", description: "OPS-ONLY. Enqueue a NEW clearance/search run the driver will pick up. Provide markName (or marks[] for a batch) + forwarder (and ideally classes/goods/customer/profileKey/ref). Returns the queue id + slug; the runId/codename is assigned when the runner claims it — poll list_runs (by markName) or run_changes for progress. Spends real money once it runs.", inputSchema: { type: "object", properties: { agent: { type: "string", description: "Which agent workspace's queue. Omit for the deployment default (CLEAROTRON_QUEUE_DIR or the default agent's queue — docs/INTAKE.md)." }, markName: { type: "string", description: "The mark (single-mark form). Required unless marks[] is provided." }, marks: { type: "array", items: { type: "object", properties: { name: { type: "string" }, classes: { type: "array", items: { type: "number" } }, ref: { type: "string" } }, required: ["name"] }, description: "Batch form: EVERY name of the batch in ONE job. Only a knockout-search reads more than one name at a time; a clearance reads one, and more is refused rather than truncated." }, classes: { type: "array", items: { type: "number" }, description: "Nice classes — whole numbers 1–45 (1–34 goods, 35–45 services). classes OR goods; either suffices." }, goods: { type: "string" }, jurisdictions: { type: "array", items: { type: "string" }, description: "WHERE the search points — and, for a clearance, WHICH search it is: one country is a full-country-search, a region or two-or-more countries a multi-country-focus-search. AUTHORITATIVE (the matter frame is told not to widen past them). Omit ⇒ the project/customer default territories; send worldwide:true to search everywhere instead. Names or codes both read; max 20." }, platforms: { type: "array", items: { type: "string" }, description: "OPTIONAL per-run SCOPE: extra marketplaces to sweep, as bare store domains e.g. [\"gnc.com\"]. ADDED to the account's own marketplaces — additive only, never a replacement (a client's platform list is a mandate). Max 10; \"web\" is implicit and must not be listed." }, customer: { type: "string" }, profileKey: { type: "string", description: "The customer ACCOUNT key (see list_profiles) whose profile rates this run; omit for the neutral generic profile. REQUIRED for an accounts-scoped session (your grant names the keys — see describe_options)." }, forwarder: { type: "string", description: "Requester/reply-routing key — rides the delivery packet so the integrator knows who gets the report (docs/DELIVERY.md). Account sessions may omit it — it is stamped from your verified identity." }, forwarderEmail: { type: "string" }, ref: { type: "string" }, provider: { type: "string" }, brief: { type: "string" }, upfrontInstructions: { type: "string" }, projectKey: { type: "string", description: "OPTIONAL (spec 62): the PROJECT/engagement key UNDER profileKey (see that customer's projects[] in list_profiles) whose overlay rates this run; omit to run on the customer profile. An unknown key clarifies at intake." }, product: { type: "string", enum: ORDERABLE_PRODUCTS, description: PRODUCT_DESC }, nativeLanguage: { type: "boolean", description: "OPTIONAL, and only on a multi-country-focus-search: the native-language investigation. Send TRUE or omit the field — FALSE IS REFUSED, not honoured: the toggle only ever added, so there is nothing for false to switch off, and accepting it would let you believe you had removed a reading that runs anyway. It runs AUTOMATICALLY on a full-country-search and is not part of the other two, so asking for it there is refused rather than accepted and ignored. It routes on territory — the scope must name one it covers." }, worldwide: { type: "boolean", description: "Search EVERYWHERE, and refuse to be narrowed by the account's own default territories. This is not the same as omitting jurisdictions, which means \"whatever the account says\" — the two used to be indistinguishable on this wire, which is how a request that bought everywhere ran an account's seven countries. Never send \"Worldwide\" as a jurisdictions entry." }, recipeKey: { type: "string", description: "OPTIONAL alternative selector: a saved search (recipe) slug for this customer. Mutually exclusive with product — a saved search already carries one." }, deliveryRoute: { type: "string", enum: ["email", "portal"], description: "OPTIONAL: how the delivered packet leaves — email (default). \"portal\" is reserved for the portal delivery lane and CLARIFIES at admission until it ships (never a silent no-op)." }, parentRunId: { type: "string", description: "OPTIONAL escalation lineage: the runId this run escalates from (e.g. a knockout HIGH mark → this clearotron)." }, deliverableSpec: { type: "string" }, commercialFlexibility: { type: "string" }, priorUse: { type: "string" }, campaignShape: { type: "string", description: "Campaign-shape FACTS from the request/client — how the mark will be deployed: standalone brand vs flavour/sub-brand under a NAMED house mark; seasonal/limited vs permanent; launch scale. Verbatim facts only — the engine records them on the matter frame instead of inferring a launch shape." }, deadline: { type: "string", description: "ISO-8601 — drives the deadline envelope." }, customerUnknown: { type: "boolean" }, dupOverride: { type: "boolean", description: "Requester-confirmed force-run past matter dedup." }, clientPrincipal: { type: "boolean", description: "Set by the client portal only: this run was started by a CLIENT and consumes that account's runCaps.dailyRuns allowance. Omit for staff, agent and email-door runs — absence means uncapped, and setting it can only restrict the run that carries it." }, rawRequest: { type: "string" }, forwarderDomain: { type: "string" }, msgId: { type: "string" }, conversationId: { type: "string" }, id: { type: "string" } }, required: ["forwarder"] } },
-  { name: "stop_run", description: "OPS-ONLY. Cancel a run. Pass id to remove a not-yet-claimed queued job (a real cancel, no spend). Pass runId to file a cancel request on a started run. By default the cancel is COOPERATIVE — the sentinel is written and a turn already in flight is allowed to finish, which has no deadline: a reasoning turn can run for tens of minutes. Add immediate:true to also end that turn, so the run goes terminal in seconds.", inputSchema: { type: "object", properties: { agent: { type: "string" }, id: { type: "string", description: "A queued job id (from start_run) — dequeues before the runner claims it." }, runId: { type: "string", description: "A started run's runId — files a cancel sentinel." }, immediate: { type: "boolean", description: "Stop NOW instead of at the next step boundary. The cancel sentinel is written FIRST and then the run's own recorded engine turn is ended, in that order — the sentinel is what makes the record clean, so the terminal names the stage, the actor and the request time instead of leaving a run that reads as still running. The step in flight is lost; everything already recorded is kept. Falls back to the boundary stop, and SAYS SO in the answer, when there is no live turn to end — a run between steps, or one whose turn has already exited. Never send this expecting a guaranteed instant stop: the answer states which of the two actually happened."}, onBehalfOf: { type: "string", description: "The identifier of a human this caller has itself verified (#1378). RECORDED BESIDE the token's own principal, never instead of it — a stop by the portal for alice@x is written `portal:alice@x`, so an asserted name is never mistaken for a proved one. Bare identifiers only; anything else is dropped." } } } },
+  { name: "stop_run", description: "OPS-ONLY. Cancel a run. Pass id to remove a not-yet-claimed queued job (a real cancel, no spend). Pass runId to file a cancel request on a started run. By default the cancel is COOPERATIVE — the sentinel is written and a turn already in flight is allowed to finish, which has no deadline: a reasoning turn can run for tens of minutes. Add immediate:true to also end that turn: it is sent a stop, anything of it still running a few seconds later is killed, and the answer says the turn ended only once it has seen it end. If it could not be ended, the run ends at its next step boundary, and the answer says that instead.", inputSchema: { type: "object", properties: { agent: { type: "string" }, id: { type: "string", description: "A queued job id (from start_run) — dequeues before the runner claims it." }, runId: { type: "string", description: "A started run's runId — files a cancel sentinel." }, immediate: { type: "boolean", description: "Stop NOW instead of at the next step boundary. The cancel sentinel is written FIRST and then the run's own recorded engine turn is stopped, in that order — the sentinel is what makes the record clean, so the terminal names the stage, the actor and the request time instead of leaving a run that reads as still running. The turn is sent SIGTERM (to its whole process group when it leads one, as both engines spawn it, so the tools it started are reached too), watched, and sent SIGKILL if anything of it is still running when the grace runs out; the answer waits for that, which takes seconds. A turn that is stopped loses its step's work; everything already recorded is kept. Sending the stop is not the same as the turn ending, and the answer claims the second only when it has seen it (immediate.ended). Falls back to the boundary stop, and SAYS SO in the answer, when there is no live turn to signal — a run between steps, or one whose turn has already exited — or when the turn was still there after the SIGKILL. The answer states which of the two actually happened."}, onBehalfOf: { type: "string", description: "The identifier of a human this caller has itself verified (#1378). RECORDED BESIDE the token's own principal, never instead of it — a stop by the portal for alice@x is written `portal:alice@x`, so an asserted name is never mistaken for a proved one. Bare identifiers only; anything else is dropped." } } } },
   { name: "server_info", description: "The AGPL §13 source offer: this server's name, version, licence, source repository and the COMMIT IT IS RUNNING. Callable by every session kind — the offer is owed to whoever interacts with the service. Reads no run and no account data.", inputSchema: { type: "object", properties: {} } },
   { name: "list_outbox_events", description: "Integrator discovery read (docs/DELIVERY.md): every pending outbox event — delivered markers plus the self-contained run-failed / intake-rejected / duplicate-skipped / late-bind-ack packets. Route each, then mark_sent (delivered) or ack_event (the rest).", inputSchema: { type: "object", properties: {} } },
   { name: "get_delivery_packet", description: "The run's send payload: _driver/delivery.json (subject, recipient routing, verbatim emailBodyHtml, whatsapp line) and/or failure.json, plus sendPending/.sent state. NOT exposed to client tokens.", inputSchema: { type: "object", properties: { runId: { type: "string" } }, required: ["runId"] } },

package/package.json

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

package/portal-ui/dist/assets/{index-CWTHP0sH.js → index-CcFjgM78.js}

@@ -10943,6 +10943,7 @@ var NAV = [
 		path: "/portal/people",
 		icon: "users",
 		needs: "manage",
+		hidden: true,
 		scope: "account"
 	},
 	{
@@ -11065,6 +11066,7 @@ function avatarMenuFor(who, entries = NAV) {
 	const pick = (id) => all.find((e) => e.id === id);
 	return [
 		pick("preferences"),
+		pick("people"),
 		pick("admin.config"),
 		pick("about")
 	].filter((e) => !!e);
@@ -11405,6 +11407,9 @@ function companyFactsMap(granted, roster) {
 //#endregion
 //#region src/shell/companyRows.ts
 var GENERIC_KEY = GENERIC_ACCOUNT;
+function switcherKeys(me, roster) {
+	return [...(me.allAccounts ? (roster ?? []).map((c) => c.key) : me.accounts).filter((k) => !isGenericKey(k)), ...me.genericOrgs.map(genericFor)];
+}
 var GENERIC_LINE = "Run any clearance against the default settings, with no company set up.";
 function pickerGroups(keys, orgOf, organisations, companyName, factsFor) {
 	const rowFor = (key) => isGenericKey(key) ? {
@@ -11445,6 +11450,9 @@ function pickerGroups(keys, orgOf, organisations, companyName, factsFor) {
 function pickerRows(keys, orgOf, organisations, companyName, factsFor) {
 	return pickerGroups(keys, orgOf, organisations, companyName, factsFor).groups.flatMap((g) => g.rows);
 }
+function switcherLabel(row) {
+	return row.generic ? `${row.name} (Default)` : row.name;
+}
 //#endregion
 //#region src/shell/accessWords.ts
 function permissionsPhrase(p) {
@@ -11646,7 +11654,7 @@ function AppShell({ render }) {
 	};
 	const facts = companyFactsMap(me.accountFacts, rosterResult?.kind === "ok" ? rosterResult.value : []);
 	const factsFor = (key) => facts[isGenericKey(key) ? GENERIC_ACCOUNT : key];
-	const ownerKeys = [...(me.allAccounts ? rosterResult?.kind === "ok" ? rosterResult.value.map((c) => c.key) : [] : me.accounts).filter((k) => !isGenericKey(k)), ...me.genericOrgs.map(genericFor)];
+	const ownerKeys = switcherKeys(me, rosterResult?.kind === "ok" ? rosterResult.value : null);
 	const rosterOrgs = Object.fromEntries((rosterResult?.kind === "ok" ? rosterResult.value : []).flatMap((c) => c.org ? [[c.key, c.org]] : []));
 	const orgOf = (key) => orgOfGeneric(key) ?? me.accountOrgs[key] ?? rosterOrgs[key] ?? null;
 	const organisations = me.organisations;
@@ -11903,7 +11911,7 @@ function AppShell({ render }) {
 function BrandOwnerSwitcher({ grouped, value, onChange }) {
 	const option = (r) => (0, import_jsx_runtime.jsx)("option", {
 		value: r.key,
-		children: r.name
+		children: switcherLabel(r)
 	}, r.key);
 	return (0, import_jsx_runtime.jsxs)("select", {
 		value: value ?? "",
@@ -12523,14 +12531,6 @@ function Card({ run, ctx, onChanged }) {
 							onBoundary: () => void stop(false),
 							onCancel: () => setAsking(false)
 						}) : null,
-						stopping ? (0, import_jsx_runtime.jsx)("div", {
-							className: "home2-stopping",
-							children: took?.note ? took.note : (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
-								"Stopping — ",
-								run.step ? `letting “${run.step}” finish` : "letting the step in flight finish",
-								". A reasoning step can take tens of minutes and has no deadline. Nothing further will start, and nothing will be delivered."
-							] })
-						}) : null,
 						canAck ? (0, import_jsx_runtime.jsx)("button", {
 							type: "button",
 							className: "home2-ack",
@@ -12539,7 +12539,15 @@ function Card({ run, ctx, onChanged }) {
 							children: "Acknowledge"
 						}) : null
 					]
-				})
+				}),
+				stopping ? (0, import_jsx_runtime.jsx)("div", {
+					className: "home2-stop-note",
+					children: took?.note ? took.note : (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+						"Stopping — ",
+						run.step ? `letting “${run.step}” finish` : "letting the step in flight finish",
+						". A reasoning step can take tens of minutes and has no deadline. Nothing further will start, and nothing will be delivered."
+					] })
+				}) : null
 			]
 		})]
 	});
@@ -12633,13 +12641,13 @@ function StopChoice({ name, step, stoppable, onImmediate, onBoundary, onCancel }
 						className: "stop-choice-opt stop-choice-now",
 						onClick: onImmediate,
 						children: [(0, import_jsx_runtime.jsx)("b", { children: "Stop now" }), (0, import_jsx_runtime.jsxs)("span", { children: [
-							"Ends ",
+							"Sends a stop to ",
 							step ? (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
 								"“",
 								step,
 								"”"
 							] }) : (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: "the step in flight" }),
-							" rather than waiting for it. The run is over in seconds. That step’s work is lost; everything recorded before it is kept."
+							" rather than waiting for it. If it takes the stop the run is over in seconds; if it will not, the run stops at the next step instead. That step’s work is lost; everything recorded before it is kept."
 						] })]
 					})]
 				}),
@@ -13084,7 +13092,7 @@ function Clearances({ ctx }) {
 		})
 	});
 	if (!result) return (0, import_jsx_runtime.jsx)(Loading, {});
-	if (!runs.length) return (0, import_jsx_runtime.jsx)(FirstRun, { onNew: canRun(ctx.me) ? () => ctx.go("/portal/new") : null });
+	if (!allRuns.length) return (0, import_jsx_runtime.jsx)(FirstRun, { onNew: canRun(ctx.me) ? () => ctx.go("/portal/new") : null });
 	const allMarks = rows.flatMap((r) => r.kind === "family" ? r.marks : [r]);
 	const pickedRunIds = () => allMarks.filter((m) => picked.has(m.id)).flatMap((m) => m.reads.map((r) => r.runId));
 	const ungroupFamily = async (family) => {
@@ -13372,7 +13380,14 @@ function Clearances({ ctx }) {
 							(0, import_jsx_runtime.jsx)("th", { children: sortBtn("risk", "Risk") }),
 							(0, import_jsx_runtime.jsx)("th", { children: sortBtn("date", "Updated") })
 						] }) }),
-						(0, import_jsx_runtime.jsx)("tbody", { children: visible.map((r, i) => {
+						(0, import_jsx_runtime.jsxs)("tbody", { children: [!visible.length ? (0, import_jsx_runtime.jsx)("tr", { children: (0, import_jsx_runtime.jsx)("td", {
+							colSpan: (canGroup ? 6 : 5) + (showOwnerColumn ? 1 : 0),
+							style: {
+								padding: "22px 12px",
+								color: "var(--text-muted)"
+							},
+							children: "No clearances match this view. Pick another company above, or widen the status filter."
+						}) }) : null, visible.map((r, i) => {
 							const before = visible[i - 1];
 							const newGroup = grouped && (!before || runKey(r) !== runKey(before));
 							return (0, import_jsx_runtime.jsxs)(import_react.Fragment, { children: [newGroup ? (0, import_jsx_runtime.jsx)("tr", {
@@ -13414,7 +13429,7 @@ function Clearances({ ctx }) {
 								onRetire: canGroup ? retireMark : void 0,
 								onRetireRun: canGroup ? retireRun : void 0
 							})] }, r.id);
-						}) })
+						})] })
 					]
 				})
 			}),
@@ -19039,7 +19054,7 @@ function NewCompany({ ctx }) {
 		if (!raw.trim()) return [];
 		return parseLines(raw, spec.commaSeparated ?? false).filter((e) => !spec.item.ok(e));
 	});
-	const unmet = !typedName ? "Needs a name." : !key ? "Needs a key — type one below." : !orgChosen ? "Choose the organisation it belongs to." : refusedEntries.length ? `${refusedEntries.join(", ")} cannot be searched — fix or remove ${refusedEntries.length === 1 ? "it" : "them"}.` : null;
+	const unmet = !typedName ? "Needs a name." : !key ? "Needs a key — type one below." : !orgChosen ? orgsHeld.length === 0 ? "No organisation is filed on this install yet. File one with: clearotron start --organisation \"<name>\"" : "Choose the organisation it belongs to." : refusedEntries.length ? `${refusedEntries.join(", ")} cannot be searched — fix or remove ${refusedEntries.length === 1 ? "it" : "them"}.` : null;
 	async function create() {
 		if (unmet || busy) return;
 		setBusy(true);