clearotron 0.2.1 → 0.2.3

package/mcp-server/server.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // 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
-// trademark-artifacts-mcp — interrogate prelim trademark-clearance runs over MCP.
+// trademark-artifacts-mcp — interrogate clearotron trademark-clearance runs over MCP.
 //
 // One stdio binary, any number of consumers: an operator's own agent platform spawns it, and the user's
 // own Claude spawns the SAME binary, as an account that can read the run-dirs.
@@ -15,7 +15,7 @@
 //: it queues the experiment into the run dir and driver/whatif-worker.mjs runs
 // it, which is how a client reaches the engine without a remote face ever shelling.
 //
-// Imports the prelim-driver read-only via ./lib/* — touches no driver/template/deploy file.
+// Imports the clearotron-driver read-only via ./lib/* — touches no driver/template/deploy file.
 
 import "../shared/env-local.mjs";   // side effect: apply <repo>/.env when THIS file is the CLI entry (never on library import)
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -54,6 +54,13 @@ import { accountRun, accountTrace, accountTimeline, accountFinding, accountFindi
   accountWhatIfPlan, accountWhatIfQueued, accountWhatIfResult, CLIENT_FAILURE_NOTE as clientFailureNote } from "./lib/audit-view.mjs";
 import { scrubMarkdown, scrubBody, scrubFrontMatter, scrubCards } from "./lib/scrub.mjs";
 import { evidenceRecords, searchLog, coverageStatement } from "./lib/evidence.mjs";
+// The knockout lane's projections. Every audit tool below branches on `isKnockoutRun` because the
+// clearance projections read artifacts this product does not write, and returned empty rather than saying
+// so (tracker issue 275).
+import {
+  isKnockoutRun, knockoutDoc, knockoutArtifacts, knockoutArtifactPath, knockoutFindings,
+  knockoutEvidence, knockoutSearches, knockoutCoverage, traceKnockout, notProducedOnThisProduct,
+} from "./lib/knockout.mjs";
 import { instructionsFor } from "./lib/instructions.mjs";
 import { isEntrypoint } from "../shared/is-entrypoint.mjs";   // — one entry-point test, all spellings
 import { BRAND } from "../shared/brand.mjs";   // — the operator name a client is told to expect, from the tenant seam
@@ -82,6 +89,18 @@ function mustRun(runId) {
 function artifactPath(run, name) {
   const { P, runDir } = run;
   if (name === "status.json") return join(runDir, "status.json");
+  // THE KNOCKOUT TABLE IS TERMINAL ON A KNOCKOUT, and both halves of that matter (tracker issue 275).
+  //
+  // Resolving FIRST is what fixes `report`: a knockout's report.md is written to the POOL and never into
+  // the run dir, so the clearance table returned the run dir's own `report` slot — a path that does not
+  // exist — and the tool answered `exists: false` about a file sitting on disk.
+  //
+  // Not FALLING THROUGH is the other half, and it was caught by an arm rather than by design. With a
+  // fall-through, `read_artifact narrative` on a knockout resolves against the clearance table, finds the
+  // slot, and returns `exists: false` — reporting a document this product never writes as a missing one.
+  // That is the defect this issue is about, reappearing one layer down. Returning null instead makes the
+  // tool refuse the name and name the artifacts this run actually has.
+  if (isKnockoutRun(run)) return knockoutArtifactPath(run, name);
   if (name === "run.jsonl" || name === "telemetry/run.jsonl") return driverDir(runDir, "run.jsonl");
   if (REGISTER_AXES.includes(name)) return P.registerUnit(name);
   // validate the axis against the known set — never let a "registerUnit:../../x" escape the run-dir
@@ -93,6 +112,10 @@ function artifactPath(run, name) {
 }
 
 function listArtifacts(run) {
+  // The error message a caller sees when a name does not resolve is built from this list, so on a knockout
+  // it has to name the knockout's own artifacts — otherwise the tool refuses a name and then suggests
+  // eleven documents this product does not write.
+  if (isKnockoutRun(run)) return knockoutArtifacts(run).filter((a) => a.exists).map(({ name, file }) => ({ name, file }));
   const { P } = run; const out = [];
   for (const [k, v] of Object.entries(P)) { if (k === "runDir" || typeof v === "function") continue; if (existsSync(v)) out.push({ name: k, file: basename(v) }); }
   for (const ax of REGISTER_AXES) { const p = P.registerUnit(ax); if (existsSync(p)) out.push({ name: `registerUnit:${ax}`, file: basename(p) }); }
@@ -150,7 +173,7 @@ function runSummary(run) {
     sent: existsSync(join(run.runDir, ".sent")),
     // B4 (per-channel receipts, 2026-07 duplicate-email fix): channel-level delivery state, dual-read.
     // A channel counts as sent when the run's _driver/send-receipts.json has that channel's receipt
-    // (prelim-deliver writes one right after EACH send lands, before the final .sent) OR the legacy
+    // (clearotron-deliver writes one right after EACH send lands, before the final .sent) OR the legacy
     // all-channels .sent marker exists (pre-receipts runs wrote only that, after both sends). SKILL.md
     // step 2b reads this on a retry to skip already-receipted channels instead of re-emailing.
     channels: channelState(run.runDir),
@@ -209,7 +232,7 @@ const tools = {
         projects: (byCustomer.get(p.key) ?? []).sort((a, b) => a.key.localeCompare(b.key)) }))
       .sort((a, b) => a.key.localeCompare(b.key));
     return {
-      _note: "Customer roster for intake resolution. Resolve by JUDGMENT — an explicit name, a misspelling (\"Zefyr\"→zephyr), or an implicit reference (\"our functional-beverage client\") all map to a key. Set the job's profileKey to the chosen customer key; OMIT it for a new/unknown customer (⇒ the neutral generic profile). If the request names a specific PROJECT/engagement under that customer (listed in `projects[]`), also set projectKey to that project's key; OMIT projectKey when no project is meant (⇒ the customer profile). CLARIFY if you cannot tell either. Never pick a profile from the sender's email domain.",
+      _note: "Customer roster for intake resolution. Resolve by JUDGMENT — an explicit name, a misspelling of one of the keys below, or an implicit reference (\"our functional-beverage client\") all map to a key. Set the job's profileKey to the chosen customer key; OMIT it for a new/unknown customer (⇒ the neutral generic profile). If the request names a specific PROJECT/engagement under that customer (listed in `projects[]`), also set projectKey to that project's key; OMIT projectKey when no project is meant (⇒ the customer profile). CLARIFY if you cannot tell either. Never pick a profile from the sender's email domain.",
       clients,
       genericFallback: "generic",
     };
@@ -227,6 +250,28 @@ const tools = {
   get_run({ runId }) {
     const run = mustRun(runId);
     const { stages, failover } = getStages(run.runDir);
+    // THE LANE DECIDES THE ARTIFACT LIST. Appending REGISTER_AXES unconditionally is what manufactured
+    // eleven `exists: false` rows on a product that writes none of those documents — a wall of false
+    // negatives, which a reader is entitled to read as a run with nothing on disk.
+    if (isKnockoutRun(run)) {
+      const doc = knockoutDoc(run);
+      const negatives = knockoutFindings(run, { kind: "negatives" }).items;
+      return {
+        run: runSummary(run),
+        product: "knockout",
+        stages, failover,
+        artifacts: knockoutArtifacts(run),
+        coverageSummary: {
+          // No ledger EXISTS on this lane, and saying so as a fact beats reporting it as a missing file.
+          coverageLedgerPresent: false,
+          coverageLedgerNote: "A Knockout search keeps no coverage ledger; get_search_coverage answers "
+            + "from the run's own per-mark record instead.",
+          complete: Boolean(doc),
+          findings: knockoutFindings(run).items.length,
+          negativeResults: negatives.length,
+        },
+      };
+    }
     return {
       run: runSummary(run),
       stages, failover,
@@ -249,6 +294,18 @@ const tools = {
   },
   list_findings({ runId, kind, sourceLayer, group }) {
     const run = mustRun(runId);
+    if (isKnockoutRun(run)) {
+      // `group` is the clearance report's on-field/off-field/out-of-scope curation. A knockout report has
+      // no such sectioning, so the honest answer names that rather than filtering to nothing.
+      if (group) {
+        return {
+          _note: BRIEFING_NOTE, kind: "cards", group, items: [],
+          ...notProducedOnThisProduct("on-field/off-field/out-of-scope card groups",
+            "Call list_findings without `group` for this run's findings, each with its band."),
+        };
+      }
+      return { _note: BRIEFING_NOTE, ...knockoutFindings(run, { kind, sourceLayer }) };
+    }
     if (group) { const cards = loadCards(run.P); return { _note: BRIEFING_NOTE, kind: "cards", group, items: cards.cards.filter((c) => c.group === group), note: cards.note }; }
     return { _note: BRIEFING_NOTE, ...filterFindings(run.P, { kind, sourceLayer }) };
   },
@@ -256,17 +313,20 @@ const tools = {
   // Data, not narrative: no BRIEFING_NOTE rides on these. The projections — and the reasoning about what
   // is evidence and what is method — live in lib/evidence.mjs; nothing is decided here.
   list_evidence({ runId, layer }) {
-    const out = evidenceRecords(mustRun(runId));
+    const run = mustRun(runId);
+    const out = isKnockoutRun(run) ? knockoutEvidence(run) : evidenceRecords(run);
     return layer ? { ...out, records: out.records.filter((r) => r.layer === layer) } : out;
   },
   list_searches({ runId, outcome }) {
-    const out = searchLog(mustRun(runId));
+    const run = mustRun(runId);
+    const out = isKnockoutRun(run) ? knockoutSearches(run) : searchLog(run);
     if (!outcome) return out;
     const searches = out.searches.filter((s) => s.outcome === outcome);
     return { ...out, count: searches.length, searches, totalCount: out.count };
   },
   get_search_coverage({ runId }) {
-    return coverageStatement(mustRun(runId));
+    const run = mustRun(runId);
+    return isKnockoutRun(run) ? knockoutCoverage(run) : coverageStatement(run);
   },
   get_finding({ runId, id }) {
     const run = mustRun(runId);
@@ -275,7 +335,12 @@ const tools = {
     return f;
   },
   trace({ runId, target, depth, shallow }) {
-    return trace(mustRun(runId), target, { depth: depth ?? 2, shallow: shallow === true });
+    const run = mustRun(runId);
+    // The clearance trace's target table is built from STAGE_ORDER, the register axes and the clearance
+    // findings spine, so on a knockout it resolved nothing at all — including "verdict" — and its error
+    // enumerated fifteen stages, none of them from this lane.
+    if (isKnockoutRun(run)) return traceKnockout(run, target, readEvents(run.runDir));
+    return trace(run, target, { depth: depth ?? 2, shallow: shallow === true });
   },
   get_telemetry({ runId, stage, axis }) {
     const run = mustRun(runId);
@@ -484,7 +549,7 @@ const TOOL_DEFS = [
   // comes back. The brief names WHICH PRODUCT the run was instead, resolved from the registry.
   { name: "brief", description: "START HERE for any 'what do you have on X / what did the search find' question — ONE plain-language briefing of a run, in the client-voiced wording (which search product this run was, overall risk in plain words, each conflict in 1–2 plain sentences, any conditions on the result). Facts, never advice. No internal stage names, no risk-formula codes, no model names. Reach for the audit tools (get_run, trace, decision_timeline, get_telemetry) only when the user asks HOW the system reached a conclusion.", inputSchema: { type: "object", properties: { ...runIdProp }, required: ["runId"] } },
   { name: "list_runs", description: "List the searches on this account (in progress and finished), newest first. TO FIND A SEARCH BY THE NAME IT CLEARED, pass `mark` — the stored identifier is a longer prefixed slug a client has never seen, so a bare mark name will not match `slug`. If a filtered call comes back empty, list unfiltered and read down the mark names before telling anyone there is nothing there. States: 'postponed' = paused on a provider cap and resuming by itself (resetsAt); 'recovering' = backing off and retrying (recoveryResumesAt); 'parked-for-human' = interrupted mid-search, resumes on the next activation. sendPending:true is the authoritative list of finished searches still owed their delivery notification. Follow up with brief for a plain-language summary of one search.", inputSchema: { type: "object", properties: { agent: { type: "string" }, state: { type: "string", enum: ["running", "delivered", "failed", "postponed", "recovering", "parked-for-human", "cancelled"] }, mark: { type: "string", description: "Find a search by the MARK it cleared: matches the mark name or the identifier, case-insensitively, on part of the word. This is the parameter a name-shaped question wants." }, slug: { type: "string", description: "EXACT identifier match, for a caller that already holds one. A mark name is not a slug — use `mark`." }, sendPending: { type: "boolean", description: "true = only searches still owed a delivery notification; false = only already-settled ones." }, limit: { type: "number" } } } },
-  { name: "list_profiles", description: "List the customer ACCOUNTS the firm runs prelim clearances for (key + name + industry + their PROJECTS) — the roster the intake step resolves a job's profileKey (and optional projectKey) against. profileKey selects that customer's marketplaces, default classes/jurisdictions, report format and risk posture; a project (spec 62) is an engagement UNDER a customer that overlays its own marketplaces/classes/sector/posture. Resolve by JUDGMENT (explicit name, misspelling, or implicit reference); OMIT profileKey for a new/unknown customer (uses the neutral generic profile); set projectKey only when the request names a specific project in that customer's projects[], else OMIT it (runs on the customer profile); never pick a profile from the sender's email domain. Read-only.", inputSchema: { type: "object", properties: {} } },
+  { name: "list_profiles", description: "List the customer ACCOUNTS the firm runs clearotron clearances for (key + name + industry + their PROJECTS) — the roster the intake step resolves a job's profileKey (and optional projectKey) against. profileKey selects that customer's marketplaces, default classes/jurisdictions, report format and risk posture; a project (spec 62) is an engagement UNDER a customer that overlays its own marketplaces/classes/sector/posture. Resolve by JUDGMENT (explicit name, misspelling, or implicit reference); OMIT profileKey for a new/unknown customer (uses the neutral generic profile); set projectKey only when the request names a specific project in that customer's projects[], else OMIT it (runs on the customer profile); never pick a profile from the sender's email domain. Read-only.", inputSchema: { type: "object", properties: {} } },
   { name: "get_run", description: "ENGINEERING/AUDIT view — full run mechanics: status, every pipeline stage (trigger/outcome), failover facts, artifact validity, and a coverage summary. Use when the user asks how the run executed; for 'what did it find', call brief instead.", inputSchema: { type: "object", properties: { ...runIdProp }, required: ["runId"] } },
   { name: "read_artifact", description: "Read a run artifact's raw text (or one '# Section', or its front-matter). For briefing a person, the report is the plain-language layer; the rest are internal working documents. Names: report, audit, narrative, registerFindings, commonLaw, placement, matterContext, variantManifest, skepticFlags, seniorEyeReview, caseLaw, clientSummary (internal cover-note source; ops only), a register axis (e.g. primary-sweep), status.json, run.jsonl.", inputSchema: { type: "object", properties: { ...runIdProp, name: { type: "string" }, section: { type: "string", description: "Return only this '# Section'." }, frontMatterOnly: { type: "boolean" } }, required: ["runId", "name"] } },
   { name: "list_evidence", description: "The records this search considered — every register and common-law entry, including ones the report does not name individually. Each carries the mark, owner and country, the classes, the register status, the source link, whether the provider record was actually retrieved (`retrieved`), and `superseded: true` if a later pass withdrew it. Use this to answer 'what exactly did you find, and who owns it?'. Filter with layer: register | common-law.", inputSchema: { type: "object", properties: { ...runIdProp, layer: { type: "string", enum: ["register", "common-law"] } }, required: ["runId"] } },
@@ -509,7 +574,7 @@ const TOOL_DEFS = [
   { name: "describe_options", description: "START HERE before composing a search — the option space, for free. Returns the four searches this deployment can actually run — each with the geography it accepts, how many names it reads, its turnaround, whether it carries the case-law reading, whether the native-language investigation is optional or automatic, and a plain note when one is unavailable — plus the combination rules the servers enforce (territories, native-language routing, marketplaces, classes, names per search), and — for a client connector — YOUR OWN account: its key (the profileKey plan_run and start_run require), its projects, its saved searches (the recipeKey slugs) and what is left of today's allowance. Omit profileKey to be answered about your own account(s); pass it to ask about a specific one. Reserves nothing, spends nothing, starts nothing. Then: plan_run (free) with the arguments you intend, and start_run with the SAME arguments once the requester has confirmed.", inputSchema: { type: "object", properties: { profileKey: { type: "string", description: "OPTIONAL: the customer ACCOUNT key to describe. Omit it to be answered about the account(s) this session holds — that is how a client connector discovers the key it must pass to plan_run/start_run." } } } },
   { 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 prelim)." }, 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: "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 (tracker issue 2076). 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: "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: {} } },
@@ -713,7 +778,7 @@ export function attachHandlers(server, { scope = { kind: "ops", runId: null }, l
   });
 
   server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
-    resourceTemplates: [{ uriTemplate: "trademark://run/{runId}/{artifact}", name: "prelim run artifact", description: "Raw text of a run artifact (report, audit, narrative, registerFindings, commonLaw, matterContext, a register axis, status.json, run.jsonl).", mimeType: "text/markdown" }],
+    resourceTemplates: [{ uriTemplate: "trademark://run/{runId}/{artifact}", name: "clearotron run artifact", description: "Raw text of a run artifact (report, audit, narrative, registerFindings, commonLaw, matterContext, a register axis, status.json, run.jsonl).", mimeType: "text/markdown" }],
   }));
   server.setRequestHandler(ListResourcesRequestSchema, async () => {
     // / AGPL §13 — LISTED FIRST, AND FOR EVERY SCOPE. An offer nobody can find is not an offer, and
@@ -948,6 +1013,6 @@ export { tools, TOOL_DEFS, NS, log };
 const isMain = isEntrypoint(import.meta.url);
 if (isMain) {
   makeServer().connect(new StdioServerTransport())
-    .then(() => log("ready — read-only interrogation + gated what-if over prelim runs"))
+    .then(() => log("ready — read-only interrogation + gated what-if over clearotron runs"))
     .catch((e) => { log(`fatal: ${e?.stack ?? e}`); process.exit(1); });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clearotron",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
   },
   "description": "Clearotron — trademark-clearance engine: deterministic orchestration driver + MCP interrogation server. Provider-agnostic, model-agnostic, runs headless (no gateway).",
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.13.0"
   },
   "workspaces": [
     "driver",
@@ -22,6 +22,7 @@
     "portal-ui"
   ],
   "scripts": {
+    "preinstall": "node scripts/preinstall-node-check.mjs",
     "postinstall": "node -e \"const{existsSync}=require('node:fs');const{execFileSync}=require('node:child_process');if(existsSync('scripts/install-hooks.mjs'))execFileSync(process.execPath,['scripts/install-hooks.mjs'],{stdio:'inherit'})\"",
     "prepack": "node scripts/write-build-info.mjs",
     "prepublishOnly": "node scripts/release-completeness-check.mjs",
@@ -38,10 +39,10 @@
     "contract-dictation": "node scripts/contract-dictation-scan.mjs",
     "drain-preflight": "node scripts/drain-preflight.mjs",
     "report-frame-check": "node scripts/report-frame-check.mjs",
-    "dead-names": "node scripts/dead-names.mjs",
+    "retired-settings": "node scripts/dead-names.mjs",
     "authority-probe": "node scripts/authority-boundary-probe.mjs",
     "engine-probe": "node scripts/engine-probe.mjs",
-    "seat-retry": "node scripts/seat-retry-report.mjs",
+    "retry-report": "node scripts/seat-retry-report.mjs",
     "tokens": "node shared/tools/emit-tokens.mjs",
     "tokens:check": "node shared/tools/emit-tokens.mjs --check",
     "sync:uspto": "node bin/uspto-sync.mjs",
@@ -72,7 +73,7 @@
     "buffers": "file:vendor/buffers",
     "exceljs": "^4.4.0",
     "jose": "^6.2.3",
-    "undici": "^8.10.1"
+    "undici": "^7.29.1"
   },
   "bin": {
     "clearotron": "bin/clearotron.mjs"
@@ -105,13 +106,30 @@
     "portal-ui/dist/",
     "portal-ui/package.json",
     ".env.example",
-    "!driver/profiles/aurora.json",
-    "!driver/profiles/zephyr.json",
-    "!driver/profiles/petcary.json",
-    "!driver/profiles/petcary.context.md",
-    "!driver/profiles/projects/aurora/",
-    "!driver/recipes/aurora/",
-    "!driver/recipes/zephyr/",
+    "!driver/profiles/*.json",
+    "driver/profiles/generic.json",
+    "driver/profiles/demo-brand-owner.json",
+    "!driver/profiles/*.context.md",
+    "!driver/profiles/projects/*/",
+    "driver/profiles/projects/demo-brand-owner/",
+    "!driver/recipes/*/",
+    "!driver/skills/prelim-search/risk-framework-*",
+    "driver/skills/prelim-search/risk-framework.md",
+    "driver/skills/prelim-search/risk-framework.manifest.json",
+    "driver/skills/prelim-search/risk-framework-demo.md",
+    "driver/skills/prelim-search/risk-framework-demo.manifest.json",
+    "driver/skills/prelim-search/risk-framework-triage.md",
+    "driver/skills/prelim-search/risk-framework-triage.manifest.json",
+    "!driver/skills/prelim-search/worked-examples-*",
+    "driver/skills/prelim-search/worked-examples.md",
+    "driver/skills/prelim-search/worked-examples-demo.md",
+    "!scripts/home-render-check.mjs",
+    "!scripts/ai-page-render-check.mjs",
+    "!scripts/composer-render-check.mjs",
+    "!scripts/clearances-render-check.mjs",
+    "!scripts/portal-lifecycle-check.mjs",
+    "!scripts/test-account-names.mjs",
+    "!scripts/no-test-account-reaches-the-package.mjs",
     "!**/test/",
     "!**/bench/",
     "!**/*.test.mjs",

package/portal-ui/dist/assets/{index-Ct3iQtZ2.css → index-1ziUJX1E.css}

@@ -598,7 +598,7 @@ table.data tr.row:hover td {
 /* tracker issue 277 — A SECTION HEADER, not a decorative divider.
    Brand owner is the organising principle of the whole list, and a reader had to work it out: the name
    was set in the smallest, lowest-contrast, most letterspaced type on the page, which reads as a rule
-   BETWEEN rows rather than as "everything below this belongs to Aurora Interactive".
+   BETWEEN rows rather than as "everything below this belongs to Foxglade Interactive".
    Body-text size, medium weight, full-strength ink, sentence case rather than letterspaced caps — and a
    hairline rule spanning the table beneath it, so containment is visible without reading anything. */
 table.data tr.group-head td {
@@ -916,11 +916,21 @@ input.filter {
   color: var(--text-strong);
 }
 
+/* Says what the row of pills below it is a row OF. Sentence case and body-weight rather than the
+   uppercase section treatment above: this is a caption belonging to the statement it follows, and
+   giving it a heading's weight would make it look like a new section — which is the misreading the
+   label exists to end. Sits tight to its pills and away from the statement above. */
+.fw-ladder-label {
+  font-size: 12px;
+  color: var(--text-muted);
+  margin: 14px 0 0;
+}
+
 .fw-ladder {
   display: flex;
   flex-wrap: wrap;
   gap: 6px;
-  margin: 10px 0 4px;
+  margin: 6px 0 4px;
 }
 
 .fw-bmh {
@@ -991,6 +1001,37 @@ input.filter {
   max-width: 420px;   /* tracker issue 2086 — the note's width is the note's own, not its call site's */
 }
 
+/* The line beside the primary action: what happens next when it is available, and why it is not when
+   it is not. Capped here rather than at the call site for the same reason the note above is — width is
+   a decision this file makes. Narrower than the note because it sits IN the action row, beside a
+   button, rather than replacing it. */
+.footer-hint {
+  max-width: 260px;
+  font-size: 12px;
+  line-height: 1.4;
+  color: var(--text-muted);
+}
+
+/* The acknowledgement a save leaves beside the button that was pressed.
+   Quiet on purpose: it is a receipt, not an alert, and it sits in the same row as the primary action
+   without competing with it. No new colour — `--tone-minimal` (the palette's clear-green) and the hairline are what the rest of
+   this file already uses for a settled, good state. */
+.save-done {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  font-size: 12.5px;
+  color: var(--text-body);
+  background: var(--surface-sunken);
+  border: 1px solid var(--border-hairline);
+  border-radius: 7px;
+  padding: 7px 11px;
+}
+.save-done svg {
+  color: var(--tone-minimal);
+  flex: none;
+}
+
 .fw-meta {
   font-size: 12px;
   color: var(--text-muted);