clearotron 0.2.0 → 0.2.2

package/driver/whatif-memo-run.mjs

@@ -31,7 +31,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, renameSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { driverDir } from "../shared/driver-dir.mjs";
+import { driverDir, DRIVER_DIR } from "../shared/driver-dir.mjs";   // the subtree name from its one definition, never a literal
 import { composeMemo } from "./whatif-memo.mjs";
 
 export const SKILL_ROOT = join(dirname(fileURLToPath(import.meta.url)), "skills");
@@ -85,6 +85,43 @@ export function movedArtifacts(before = {}, after = {}) {
     .map((p) => ({ path: p, before: before[p] ?? null, after: after[p] ?? null }));
 }
 
+/**
+ * Split what moved into the memo's OWN RECORD and everything else.
+ *
+ * A memo legitimately leaves two kinds of trace on its parent. Its documents go under `_memos/`, which
+ * `digestRunDir` already skips. Its DISPATCH leaves driver telemetry — `_driver/whatif-memo.*` and an
+ * appended line in `_driver/run.jsonl` — because the memo rides the same gateway ladder as any seat and
+ * the gateway records what it dispatched. That is the parent gaining a RECORD of the memo, which is
+ * correct behaviour and the same rule the experiment path already lives by; it is not the archive being
+ * rewritten.
+ *
+ * ✕ EVERYTHING ELSE IS THE SEAT WRITING WHERE IT WAS NOT INVITED, and it is refused by name. The seat
+ * has a real file-write grant on the run directory, and on a delivered run it used it: an archived
+ * client run carries `memo-osler-coexistence.json` at its root, which is the seat's reply written to a
+ * path of its own choosing instead of to the `expectFile` it was given. That also explains the retry
+ * that preceded it — the harness looked for the reply where it had asked for it and did not find it.
+ *
+ * `run.jsonl` may only GROW. A shrink or a rewrite is not an append, and an append is the only thing a
+ * dispatch does to it. The check is on size because the digest carries `sha:size` and not the bytes; a
+ * rewrite that happened to keep the same length would pass, and that is written down rather than
+ * claimed against. PURE.
+ */
+export function splitMemoFootprint(moved = []) {
+  const own = [];
+  const foreign = [];
+  const sizeOf = (v) => { const n = Number(String(v ?? "").split(":")[1]); return Number.isFinite(n) ? n : null; };
+  for (const m of moved) {
+    const p = String(m?.path ?? "");
+    if (p.startsWith(`${DRIVER_DIR}/whatif-memo.`)) { own.push(m); continue; }
+    if (p === `${DRIVER_DIR}/run.jsonl`) {
+      const b = sizeOf(m.before); const a = sizeOf(m.after);
+      if (b !== null && a !== null && a > b) { own.push(m); continue; }
+    }
+    foreign.push(m);
+  }
+  return { own, foreign };
+}
+
 /** The profile key the PARENT rated under — read from its frozen sidecar, never re-resolved. */
 export function parentRatedUnder(runDir, { read = readFileSync } = {}) {
   try { return JSON.parse(read(driverDir(runDir, "profile.json"), "utf8"))?.profileKey ?? null; }
@@ -141,7 +178,7 @@ export async function seatReason({ runDir, runId, assumption, ratedUnder, findin
 
 /**
  * Validate the seat's reply. TYPED, not parsed prose — the reply is a JSON object the skill dictates,
- * so a phrasing choice can never fail it. That is deliberate and it is tracker issue 129's lesson applied
+ * so a phrasing choice can never fail it. That is deliberate and the lesson is applied
  * before the fact: a gate keyed on how a model worded something is one drift from killing the call.
  *
  * Returns { ok, reading } or { ok: false, fail, detail }. Refuses rather than repairing: a memo composed
@@ -299,10 +336,14 @@ export async function askArchivedRun({ runId, question, requestedBy = null } = {
 
   // AFTER the write, deliberately: the check has to cover this call's own behaviour, not merely the
   // reasoning pass's. If writing the memo touched the parent, that is exactly what must be caught.
-  const moved = movedArtifacts(before, digestRunDir(run.runDir));
-  if (moved.length)
+  const { own, foreign } = splitMemoFootprint(movedArtifacts(before, digestRunDir(run.runDir)));
+  if (foreign.length)
     return { ok: false, fail: MEMO_FAILS.PARENT_MOVED,
-      detail: `the parent run's artifacts moved during the memo: ${moved.slice(0, 5).map((m) => m.path).join(", ")}`, moved };
+      // NAMES WHAT IT FOUND AND WHY IT IS WRONG. "the parent's artifacts moved" was true of a correct
+      // memo too — the dispatch telemetry tripped it — so the sentence could not tell a reader whether
+      // the archive had been rewritten or the memo had merely run.
+      detail: `a memo may write only to ${MEMO_DIR}/ and its own reply file; these were written into the parent run instead: ${foreign.slice(0, 5).map((m) => m.path).join(", ")}`,
+      moved: foreign, memoFootprint: own };
 
   return {
     ok: true,

package/driver/whatif-queue.mjs

@@ -50,7 +50,7 @@ import { randomUUID } from "node:crypto";
 
 // ── WHICH RUNS A WHAT-IF MAY TOUCH — ONE DECLARATION, TWO READERS ───────────────────────────────────
 //
-// FOUND BY DRIVING IT (, 2026-09-03). There were THREE copies of this question and
+// FOUND BY DRIVING IT (2026-09-03). There were THREE copies of this question and
 // they did not agree. `whatIfPlan` and `whatIfEnqueue` refused `location === "archive" || state ===
 // "delivered"`; the worker refused the presence of any of `.delivered`, `.failed`, `.cancelled`,
 // `.cancel`. A run that had FAILED passed the first two and was refused by the third — so a client could

package/driver/whatif-worker.mjs

@@ -119,7 +119,7 @@ async function settleOne(entry, exec) {
   if (!job) return null;                       // another worker won it, or the manifest was recorded bad
   const { runDir, id } = entry;
   // The verdict is rendered HERE and not in the scan, because only now is the job's kind known. A
-  // delivered run refuses a stage re-run and welcomes a memo — that is the whole of tracker issue 132 —
+  // delivered run refuses a stage re-run and welcomes a memo — that is the whole distinction —
   // and a scan over run directories cannot tell those apart.
   const refusal = whatIfRefusal({ markers: entry.markers ?? [], kind: job.op?.kind ?? "stage" });
   if (refusal) {

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,17 @@
 # trademark-artifacts-mcp
 
+## 0.2.2
+
+## 0.3.0-beta.0
+
+## 0.2.1
+
+## 0.2.1-beta.2
+
+## 0.2.1-beta.1
+
+## 0.2.1-beta.0
+
 ## 0.2.0
 
 ## 0.1.12

package/mcp-server/README.md

@@ -1,9 +1,9 @@
 # trademark-artifacts-mcp
 
-An MCP server to **interrogate prelim trademark-clearance runs** — for an integrator's agent platform and for
+An MCP server to **interrogate clearotron trademark-clearance runs** — for an integrator's agent platform and for
 your **own Claude** (Claude Code / Desktop) alike. One stdio binary, two consumers.
 
-It answers three kinds of question against any run the `prelim-driver` produced:
+It answers three kinds of question against any run the `clearotron-driver` produced:
 1. **"How did you reach Y?"** — `trace` walks the full logic flow from any point (a stage, an artifact, a
    finding, the verdict) back through the stage that emitted it, its model + any failover, its inputs (with the
    sha each input had *when consumed* vs now), the per-search audit-trail rationale, the search terms + record
@@ -15,7 +15,7 @@ It answers three kinds of question against any run the `prelim-driver` produced:
 
 ## Design
 
-- **Imports the `prelim-driver` read-only** via `lib/driver.mjs` (the single coupling point). It hardcodes **no**
+- **Imports the `clearotron-driver` read-only** via `lib/driver.mjs` (the single coupling point). It hardcodes **no**
   artifact filename or stage name, so the driver can rename artifacts freely — the server tracks
   `paths()` / `STAGE_ORDER` automatically. It edits **no** driver, template, or deploy file.
 - **Provenance from the self-describing `_driver/run.jsonl`** (each `stage` event records its own

package/mcp-server/http-server.mjs

@@ -27,6 +27,9 @@ import { envFileRead } from "../shared/env-local.mjs";   // side effect: apply t
 import { envFrom } from "../shared/env-aliases.mjs";   // — a refusal names the name in force
 import { accessAudience, audienceLabel } from "../shared/access-audience.mjs";   // — F54; jose-free on purpose
 import { doorPostureVerdict } from "./door-posture.mjs";   // — say when this door's mode came from another door's variables
+// The local key door (tracker issue 174): a second listener on a unix socket, so a scoped access key has
+// a path that no tunnel can forward to and the TCP door never learns about keys.
+import { keyDoorRefusal, openKeyDoor, KEY_SOCKET_MODE } from "./key-socket.mjs";
 import { demoPostureLine } from "../driver/demo-posture.mjs";   // — the two mis-aimed warnings answer from one place
 import { createServer } from "node:http";
 import { randomUUID } from "node:crypto";
@@ -85,13 +88,17 @@ const DEV = process.env.TRADEMARK_MCP_DEV === "1";
 // the opposite of `TRADEMARK_MCP_AUTH_DISABLED` — which authenticates nobody and hands every caller
 // `local-test@disabled` — and the handler refuses outright to build the two together.
 //
-// It exists because 's one-command local install needs the trigger lane, the trigger lane is this
+// It exists because the one-command local install needs the trigger lane, the trigger lane is this
 // face, and a startup command that has to switch authentication off to reach it is the defect that
 // issue is about. The portal holds a verb-scoped, account-capped ops token; this door demands it.
 //
 // NAMED, NEVER INFERRED — the same rule wrote for PORTAL_AUTH_MODE, for the same reason. Unset
 // means exactly what it meant before this line existed, including the dev bypass still working, so a
 // deployment that loses CLEAROTRON_OIDC_AUDIENCE still refuses to start rather than quietly becoming a key door.
+// NAMED, NEVER INFERRED, like every other setting on this door: the key path is opt-in and a deployment
+// that does not set it gets exactly the door it has today. Unset is not "pick a default socket" — a
+// default path would put a key door on every install that never asked for one.
+const KEY_SOCKET = (process.env.TRADEMARK_MCP_KEY_SOCKET || "").trim();
 const AUTH_MODE = (process.env.TRADEMARK_MCP_AUTH_MODE || "").trim().toLowerCase();
 const TOKEN_ONLY = AUTH_MODE === "token";
 const TEAM = process.env.CF_ACCESS_TEAM || "";
@@ -214,6 +221,19 @@ if (isMain) {
     }
   }
 
+  // ── THE KEY PATH, ON THE POSTURE SURFACE (tracker issue 174) ──────────────────────────────────────
+  //
+  // An operator must be able to see that a local key path exists, and with what permissions, WITHOUT
+  // reading a unit file — the acceptance asks for exactly that, and it is the same reasoning as the
+  // posture line above: a door whose shape can only be learned by reading configuration is a door whose
+  // shape nobody checks. The mode is printed in octal because that is how an operator reads `ls -l`.
+  //
+  // The ABSENT case is a line too. Silence would leave "this deployment has no key path" and "this build
+  // does not have the feature" looking identical, which is the confusion this issue is about.
+  log(KEY_SOCKET
+    ? `key path: ${KEY_SOCKET} (mode ${KEY_SOCKET_MODE.toString(8)} once open) — a scoped access key is accepted HERE and nowhere else; the network door never honours one`
+    : "key path: none configured (TRADEMARK_MCP_KEY_SOCKET unset) — a program on this box holding an access key has no door on this process");
+
   // ── THE ROSTER THIS PROCESS CAN ACTUALLY SEE ──────────────────────────────────────────────────────
   //
   // WHAT THIS EXISTS FOR. `start_run` validates `profileKey` against `loadProfiles()`, which reads
@@ -297,4 +317,27 @@ if (isMain) {
     port: PORT, host: HOST, what: "the MCP staff surface", portVar: "TRADEMARK_MCP_HTTP_PORT", portSource: PORT_CHOICE.source, portFile: envFileRead(), log,
     onReady: ({ port: bound }) => log(`listening on http://${HOST}:${bound}/mcp — READ-ONLY staff surface, firmDomains=[${ALLOWED_DOMAINS.join(", ")}], ${door}`),
   });
+
+  // ── THE SECOND DOOR: A LOCAL KEY PATH ON A UNIX SOCKET (tracker issue 174) ────────────────────────
+  //
+  // One process, two transports, two handlers. The TCP door above is untouched and still never honours a
+  // key; this one takes a scoped access key and cannot be reached from any network. A tunnel forwards to
+  // a port, so it cannot reach a socket — which is the whole reason the discriminator is the transport
+  // rather than the peer address. See key-socket.mjs for why a loopback check is not a control here.
+  //
+  // A SEPARATE SESSION MAP, deliberately. The handler already refuses a session whose owner is not the
+  // caller, so sharing one map would probably be safe — but "probably safe" across an authentication
+  // boundary is the kind of reasoning this repository keeps paying for, and two maps cost one allocation.
+  // A session minted behind the key door is not addressable from the tunnel-facing one at all.
+  if (KEY_SOCKET) {
+    const refusal = keyDoorRefusal({ authDisabled: AUTH_DISABLED, accessFile: envFrom(process.env, "CLEAROTRON_ACCESS_FILE"), authMode: AUTH_MODE });
+    if (refusal) { log(`FATAL: ${refusal}`); process.exit(1); }
+    const keyHandler = makeHttpHandler({
+      verify: null, tokenOnly: true, devMode: false,
+      limiter, opsLimiter, sessions: new Map(), createSession, ns: NS, sessionMax: SESSION_MAX,
+      authHeader: AUTH_HEADER, firmDomains: ALLOWED_DOMAINS, log,
+    });
+    openKeyDoor({ handler: keyHandler, path: KEY_SOCKET, log })
+      .catch((e) => { log(`FATAL: could not open the key socket at ${KEY_SOCKET} — ${e.message}`); process.exit(1); });
+  }
 }

package/mcp-server/key-socket.mjs

@@ -0,0 +1,184 @@
+// 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
+// key-socket.mjs — the local key door, on a unix socket, beside the TCP door that takes a proxy identity
+// (tracker issue 174).
+//
+// ── THE PROBLEM, AND WHY THE OBVIOUS FIX IS NOT ONE ─────────────────────────────────────────────────
+//
+// This interface serves two populations that authenticate differently: people arriving through a tunnel,
+// who prove themselves with a proxy JWT, and programs on the same machine holding a scoped access key,
+// which can never produce a JWT. The handler refuses to do both — `tokenOnly` and `verify` are mutually
+// exclusive by construction — so a deployment needing both has had to run the process twice. On the
+// production install that cost an outage: the shared instance was switched to the proxy mode so the
+// desktop path would work, which silently took the portal's trigger with it, and both sides logged a
+// true sentence that was not the one the operator needed.
+//
+// "ONLY ACCEPT A KEY FROM LOOPBACK" DOES NOT WORK HERE, and this is the whole design. The tunnel daemon
+// runs ON the box and connects to the listener over loopback, so a request forwarded from the internet
+// and a request from the local portal have the SAME peer address. A peer-IP check would accept a stolen
+// key replayed through the tunnel, and it would look correct in every test written on a box with no
+// tunnel — green, and wrong exactly where it matters.
+//
+// ── THE DISCRIMINATOR IS THE TRANSPORT ──────────────────────────────────────────────────────────────
+//
+// A tunnel forwards to a TCP port. It cannot reach a unix socket. So the key door is a SECOND listener
+// on a socket, and the TCP door keeps the proxy rule unchanged and never learns about keys.
+//
+// REFUSAL BY CONSTRUCTION, NOT BY A CHECK. The two handlers are separate objects: the TCP one is built
+// with `verify` and `tokenOnly:false`, this one with `verify:null` and `tokenOnly:true`. "A key
+// presented on the TCP port is refused" is therefore not a branch anybody can delete — there is no code
+// path on that handler that reads a key at all, and the existing mutual-exclusion guard keeps it that
+// way. Filesystem permissions then state which local accounts may present a key, which is a stronger
+// claim than any header check and one an operator can read with `ls -l`.
+import { createServer } from "node:http";
+import { connect } from "node:net";
+import { chmodSync, statSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** The socket's mode: owner and group read/write, nobody else. The group is the door's own egid. */
+export const KEY_SOCKET_MODE = 0o660;
+
+/**
+ * The refusals that bind on the key door WHATEVER transport it listens on.
+ *
+ * WHY THIS FUNCTION EXISTS RATHER THAN REUSING THE TOKEN-MODE BLOCK. Those refusals live inside
+ * `if (TOKEN_ONLY)` in http-server.mjs, and this door opens on a process that is typically NOT in token
+ * mode — it is in proxy mode for its TCP half. Without this, adding a key door to a proxy-mode process
+ * would skip every one of them, and the grants-file refusal is the one that matters: a missing grants
+ * file with `firmStaff` ever flipped back on is silent read-all across every customer.
+ *
+ * TWO OF THE FOUR TOKEN-MODE REFUSALS DELIBERATELY DO NOT APPEAR HERE, and saying which and why is the
+ * point — a fence that disappears without a sentence is how the next one goes:
+ *
+ *   · the loopback-only refusal guards a key riding plaintext to ANOTHER MACHINE. A unix socket has no
+ *     host and no wire; it is a filesystem object and cannot be addressed off the box at all. The hazard
+ *     it names does not exist here, and filesystem mode replaces it.
+ *   · the allowed-hosts refusal arms DNS-rebinding protection, which is an attack on a browser resolving
+ *     a HOSTNAME. A socket has no hostname and no DNS. Same reasoning.
+ *
+ * Both still bind on the TCP token door, untouched.
+ *
+ * @returns {string|null} the refusal sentence, or null when the door may open.
+ */
+export function keyDoorRefusal({ authDisabled, accessFile, authMode = "" }) {
+  // THE COMBINATION THAT MAKES BOTH DOORS KEY DOORS, and the one this whole issue exists to prevent.
+  //
+  // The mutual exclusion in makeHttpHandler is between `verify` and `tokenOnly` on ONE handler. It says
+  // nothing about two handlers in one process — and the TCP handler is built with `tokenOnly: TOKEN_ONLY`,
+  // which is `TRADEMARK_MCP_AUTH_MODE === "token"`. So with the mode set to token AND a socket configured,
+  // BOTH listeners accept a key, the TCP one is reachable through the tunnel, and the posture line below
+  // would announce that a key is "accepted HERE and nowhere else" while that is false.
+  //
+  // The loopback refusal in token mode does not save it: the tunnel daemon runs on this box and connects
+  // over loopback, which is the exact reason this door is a socket rather than a loopback port.
+  //
+  // AND IT IS THE LIKELY CONFIGURATION, not a contrived one. The deployment this issue was raised from is
+  // in token mode today, because somebody switched it to make one path work. An operator adding the socket
+  // is far more likely to leave the mode alone than to change it, so this refusal is the one that will
+  // actually fire. Found in review, not by me.
+  if (String(authMode).trim().toLowerCase() === "token") {
+    return "TRADEMARK_MCP_KEY_SOCKET is set and TRADEMARK_MCP_AUTH_MODE=token — that mode makes the NETWORK "
+      + "door take a key too, and a tunnel can reach it. The socket exists so a key has one door: unset the "
+      + "mode (the network door then takes a proxy identity) or unset the socket. Refusing to open both.";
+  }
+  if (authDisabled) {
+    return "TRADEMARK_MCP_KEY_SOCKET is set and TRADEMARK_MCP_AUTH_DISABLED=1 — one demands a valid access "
+      + "key on every request, the other authenticates nobody. Unset the bypass. Refusing to open the key door.";
+  }
+  if (!accessFile) {
+    return "TRADEMARK_MCP_KEY_SOCKET is set but CLEAROTRON_ACCESS_FILE is unset — refusing to open the key "
+      + "door. Point it at a grants file, even one containing only {\"tenants\":{}}.";
+  }
+  return null;
+}
+
+/**
+ * Is a socket at this path being served by a LIVE process, or is it a leftover?
+ *
+ * A unix socket is a file: it survives a crash, and `listen` on an existing path fails with EADDRINUSE
+ * whether or not anybody is behind it. Unlinking unconditionally is the obvious move and it is the
+ * dangerous one — it silently steals the path from a healthy sibling process, and the symptom is a portal
+ * whose calls stop arriving at a door that is still running.
+ *
+ * So: try to connect. A refused connection means nothing is listening and the file is stale. A successful
+ * one means somebody is there, and this process must refuse rather than take the path.
+ */
+export function probeSocket(path, { timeoutMs = 500 } = {}) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (v) => { if (!done) { done = true; resolve(v); } };
+    let c;
+    try { c = connect(path); } catch { return finish("stale"); }
+    const t = setTimeout(() => { try { c.destroy(); } catch { /* closing */ } finish("live"); }, timeoutMs);
+    c.on("connect", () => { clearTimeout(t); try { c.destroy(); } catch { /* closing */ } finish("live"); });
+    c.on("error", (e) => {
+      clearTimeout(t);
+      // ENOENT: no such file. ECONNREFUSED: the file is there and nothing is behind it.
+      finish(e?.code === "ENOENT" ? "absent" : e?.code === "ECONNREFUSED" ? "stale" : "unknown");
+    });
+  });
+}
+
+/**
+ * Open the key door. Resolves to `{ mode, path }` once listening.
+ *
+ * `listenOrDie` is deliberately not used: its subject is port conflicts and the explicit-port policy, and
+ * a socket path has neither. Its refusals would read as nonsense here ("set TRADEMARK_MCP_HTTP_PORT") and
+ * borrowing them would mean an operator being told to fix a variable this door does not read.
+ *
+ * THE MODE IS SET AFTER LISTEN, not before, because `listen` creates the file itself and the process
+ * umask decides what it starts as. A door that assumed its umask would be world-writable on a box whose
+ * umask was 0, which is the kind of thing nobody notices until it is the finding.
+ */
+export async function openKeyDoor({ handler, path, log = () => {}, chmod = chmodSync, stat = statSync, unlink = unlinkSync, probe = probeSocket, listen = null }) {
+  // ── THE DIRECTORY, NOT JUST THE SOCKET (found in review) ───────────────────────────────────────────
+  //
+  // 0660 on the socket says who may CONNECT to it. It says nothing about who may REPLACE it: unlinking a
+  // file is governed by write permission on the containing directory. So a socket in a world-writable
+  // directory without the sticky bit can be removed by any local account, which then binds its own
+  // listener on the path — and the portal presents its ops key to that listener. The mode on the socket
+  // does not prevent one line of it.
+  //
+  // The stale-socket handling below makes that reachable rather than theoretical: an impostor who binds
+  // first simply reads as "live", this process refuses by design, and the impostor is left holding the
+  // path with the door it replaced never having started.
+  //
+  // WORLD-WRITABLE WITHOUT STICKY IS REFUSED. Group-writable is NOT: the socket is already group-
+  // readable, so the group is the trust boundary an operator has chosen for this door, and a service
+  // directory owned by the service group at 0770 is the ordinary correct shape. The sticky bit is
+  // honoured because that is exactly what it means — /tmp is world-writable and safe for this precisely
+  // because of it.
+  const dir = dirname(path);
+  const dmode = stat(dir).mode & 0o7777;
+  if ((dmode & 0o002) && !(dmode & 0o1000)) {
+    throw new Error(`the directory holding the key socket is world-writable without the sticky bit (${dir}, mode ${dmode.toString(8)}) `
+      + "— any local account could remove this socket and bind its own listener in its place, and callers would present their key to it. "
+      + "Tighten the directory, or set the sticky bit.");
+  }
+
+  const state = await probe(path);
+  if (state === "live") {
+    throw new Error(`a process is already serving the key socket at ${path} — refusing to take the path from it. `
+      + "Stop that process, or point TRADEMARK_MCP_KEY_SOCKET somewhere else.");
+  }
+  if (state === "stale") { try { unlink(path); } catch { /* it may have gone between the probe and here */ } }
+  // THE FOURTH STATE, which was handled by accident (found in review). A socket owned by another account
+  // whose mode this process cannot reach answers EACCES — neither ENOENT nor ECONNREFUSED — and fell
+  // through to `listen`, which then failed with a bare EADDRINUSE and no sentence. That is precisely the
+  // case the probe exists for: something is at this path and this process cannot tell what.
+  if (state === "unknown") {
+    throw new Error(`something is at the key socket path and this process cannot determine what (${path}) `
+      + "— most often a socket owned by another account. Refusing to unlink a path this process cannot inspect. "
+      + "Check its owner and mode, or point TRADEMARK_MCP_KEY_SOCKET somewhere this service owns.");
+  }
+
+  const server = createServer(handler);
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    (listen ?? ((p, cb) => server.listen(p, cb)))(path, resolve);
+  });
+  chmod(path, KEY_SOCKET_MODE);
+  const mode = stat(path).mode & 0o777;
+  log(`key door listening on ${path} (mode ${mode.toString(8)}, dir ${dir} mode ${dmode.toString(8)}) — access key required, no auth proxy, unreachable from any network`);
+  return { server, path, mode };
+}

package/mcp-server/lib/audit-view.mjs

@@ -102,7 +102,7 @@ export function scrubBlocks(items) {
 /**
  * get_finding — one block.
  *
- * A WITHDRAWN block scrubs away to nothing, and the choice there is 's choice: the tool itself
+ * A WITHDRAWN block scrubs away to nothing, and the choice there is the choice: the tool itself
  * throws on a finding it cannot resolve, so returning `null` would hand a client an empty answer they
  * would believe, on the one call whose whole job is to resolve an id. It REFUSES instead, in the words
  * the record actually supports — the finding exists and was withdrawn, which is why it renders nowhere.
@@ -173,9 +173,76 @@ function accountNode(node) {
   return out;
 }
 
+// ── THE KNOCKOUT TRACE IS A DIFFERENT SHAPE, AND THE CLEARANCE ALLOWLIST DROPS ALL OF IT ────────────
+//
+// `accountTrace` below is an allowlist built field by field around the clearance trace. A Knockout trace
+// shares only `runId` and `target` with it: the fields that carry the answer are `mark`, `band`, `basis`,
+// `factors`, `counterFactors`, `findings` and `registerReads`, and none of them is in that list. So a
+// client session asking about a Knockout mark received 142 bytes of shell — and, worse, kept the `note`,
+// which reads "The band, the one-sentence ground for it, and the observations it rests on." The one field
+// that survived was a promise about the fields that did not. Measured on all four shapes: verdict
+// 303→200, mark 427→142, stage 210→95 bytes. The ops path and get_run were never affected.
+//
+// WHY THIS IS A SEPARATE PROJECTION AND NOT A WIDENED PICK LIST. Adding these names to the clearance list
+// would make a clearance trace start forwarding any same-named field it later grew, unreviewed. Each
+// shape states its own fields, so a new field on either side is invisible until somebody adds it here.
+//
+// TWO THINGS ARE PROJECTED RATHER THAN FORWARDED, both for the reason the clearance side already gives:
+//   · `events` is raw `run.jsonl` — model names, token counts and timings. It goes through `accountNode`,
+//     the same node fields the clearance walk already rules client-safe, rather than passing whole.
+//   · `basis`, `factors`, `counterFactors` and a finding's `name` are MODEL OUTPUT, so they take `clean`
+//     exactly as `summary` and `note` do on the clearance side. The knockout notes are our own literals
+//     and are cleaned anyway: a rule with an exception is a rule somebody edits the wrong way later.
+const KNOCKOUT_TRACE_KINDS = new Set(["verdict", "mark", "stage"]);
+
+/** A knockout trace, projected per shape. Only reached for a result the clearance branch cannot read. */
+function accountKnockoutTrace(result) {
+  const base = pick(result, ["runId", "target", "kind"]);
+  const cleanList = (v) => (Array.isArray(v) ? v.map(clean) : []);
+  if (result.kind === "verdict") {
+    return {
+      ...base,
+      verdict: result.verdict ?? null,
+      marks: (Array.isArray(result.marks) ? result.marks : [])
+        .map((m) => ({ ...pick(m, ["mark", "band"]), basis: clean(m?.basis ?? null) })),
+      note: clean(result.note),
+    };
+  }
+  if (result.kind === "mark") {
+    return {
+      ...base,
+      mark: result.mark ?? null,
+      band: result.band ?? null,
+      basis: clean(result.basis ?? null),
+      factors: cleanList(result.factors),
+      counterFactors: cleanList(result.counterFactors),
+      findings: (Array.isArray(result.findings) ? result.findings : []).map((f) => ({
+        ...pick(f, ["ordinal", "band"]),
+        name: clean(f?.name ?? null),
+        evidence: cleanList(f?.evidence),
+      })),
+      registerReads: (Array.isArray(result.registerReads) ? result.registerReads : [])
+        .map((r) => ({ ...pick(r, ["recordId", "band"]), read: clean(r?.read ?? null) })),
+      note: clean(result.note),
+    };
+  }
+  // stage
+  return {
+    ...base,
+    stage: result.stage ?? null,
+    events: (Array.isArray(result.events) ? result.events : []).map(accountNode),
+    produced: (Array.isArray(result.produced) ? result.produced : []).map((a) => pick(a, ["name", "file"])),
+    note: clean(result.note),
+  };
+}
+
 export function accountTrace(result) {
   if (!result || typeof result !== "object") return result;
   if (result.error) return pick(result, ["runId", "target", "error"]);   // the resolver's own guidance, no run content
+  // A clearance trace always carries `resolvedAs`; a knockout trace never does and carries a top-level
+  // `kind` instead. Requiring BOTH is what stops a clearance trace that later grows a top-level `kind`
+  // from being routed into the knockout projection and silently losing its own fields.
+  if (!result.resolvedAs && KNOCKOUT_TRACE_KINDS.has(result.kind)) return accountKnockoutTrace(result);
   const out = {
     ...pick(result, ["runId", "target", "mode"]),
     resolvedAs: pick(result.resolvedAs, ["kind", "stage", "fuzzy", "codeBuilt"]),
@@ -288,7 +355,7 @@ export function accountWhatIfPlan(result) {
 
 // The enqueue acknowledgement. It is composed in whatIfEnqueue from fields this file names, so nothing is
 // withheld here — it is declared so that a field added to that acknowledgement later cannot arrive
-// unruled, which is what 's default-deny is for.
+// unruled, which is what the default-deny is for.
 const QUEUED_FIELDS = ["queued", "runId", "experimentId", "stage", "axis", "queuedAt", "next"];
 export const accountWhatIfQueued = (result) => (result && typeof result === "object" ? pick(result, QUEUED_FIELDS) : result);
 

package/mcp-server/lib/brief.mjs

@@ -135,6 +135,21 @@ export function buildBrief(run) {
         lines.push(`- **${m.name}** — ${band}.${d.url ? ` Report: ${d.url}` : ""}`);
         for (const f of (m.findings ?? [])) {
           const who = [f.name, f.owner].filter(Boolean).join(" — ");
+          // A PROMOTED REGISTER FILING SHOWS THE RATING AND THE READ THE SEARCH ACTUALLY MADE (tracker
+          // issue 274). This line used to print `net` alone, and for a register card `net` carried the
+          // stated "no rating of its own" — so the one hard legal right on a page was described here as
+          // unrated even on runs where the assessment had written a full read of that exact filing and
+          // the report was already printing it. The page and this briefing disagreed.
+          //
+          // SCOPED TO `shape === 'register'` DELIBERATELY. Every other finding line is left exactly as it
+          // was: a typed conflict already leads with its own band on the report, and widening this to all
+          // findings would change what this briefing says about runs that have no register layer at all.
+          if (f.shape === "register") {
+            const rating = f.band ? ` — ${titleCase(String(f.band))} risk.` : "";
+            const read = f.basis && f.basis !== f.net ? ` ${f.basis}` : "";
+            lines.push(`  - ${who}${rating}${f.net ? ` ${f.net}` : ""}${read}`.trimEnd());
+            continue;
+          }
           lines.push(`  - ${who}${f.net ? `: ${f.net}` : ""}`.trimEnd());
         }
       }

package/mcp-server/lib/driver.mjs

@@ -1,6 +1,6 @@
 // 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
-// lib/driver.mjs — the SINGLE coupling point to the prelim-driver.
+// lib/driver.mjs — the SINGLE coupling point to the clearotron-driver.
 //
 // Everything the MCP imports from the deterministic driver passes through here, so the dependency surface
 // is one file: if the driver renames an export, this file fails loudly (test-caught), instead of silent
@@ -14,6 +14,12 @@ export {
   REGISTER_AXES, decideAxes, axisTier,
 } from "../../driver/stages.mjs";
 
+// The KNOCKOUT lane's own run-dir table. `paths` above is the CLEARANCE table and has no entry for any
+// file this lane writes, which is why every audit projection read a delivered knockout as a run with
+// nothing on disk (tracker issue 275). Re-exported rather than re-derived for the reason this whole file
+// 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";
+
 // 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/events.mjs

@@ -129,7 +129,7 @@ function classify(e, st, rat) {
     // dropped nothing on goods when it dropped and nobody counted". Carrying the cause is what keeps that
     // true here without alarming every ordinary run.
     //
-    // A pre- event carries no `cause`. It is left `null` and stays on the clear side: this surface
+    // A pre-change event carries no `cause`. It is left `null` and stays on the clear side: this surface
     // must not retro-label old runs as incomplete on the strength of a field their engine never wrote.
     case "screen-gate-clean": {
       const cause = e.cause ?? null;

package/mcp-server/lib/http-handler.mjs

@@ -117,7 +117,7 @@ export function makeHttpHandler({ verify, limiter, opsLimiter = null, sessions,
         try { t = verifyToken(tok); }
         catch (e) {
           // AN OPERATOR FAULT IS NOT A BAD KEY, and it must not read like one ( —
-          // bb8's F14). `isRevoked` now refuses rather than assuming a token was never revoked when the
+          // found in review). `isRevoked` now refuses rather than assuming a token was never revoked when the
           // denylist cannot be read; that is a configuration fault on THIS box, and logged in the same
           // words as a stranger presenting a bad key it would sit unnoticed in auth noise — which is how
           // the original defect survived, silently, on every default install.