clearotron 0.3.1-beta.1 → 0.3.1-beta.2

package/driver/suite-census.json

@@ -172,8 +172,8 @@
           "todos": 0
         },
         "a-connect-line-says-where-it-runs.test.mjs": {
-          "tests": 4,
-          "asserts": 14,
+          "tests": 7,
+          "asserts": 25,
           "skips": 0,
           "todos": 0
         },
@@ -400,8 +400,8 @@
           "todos": 0
         },
         "a-key-the-demo-prints-signs-for-that-demo.test.mjs": {
-          "tests": 5,
-          "asserts": 30,
+          "tests": 8,
+          "asserts": 40,
           "skips": 0,
           "todos": 0
         },
@@ -621,6 +621,12 @@
           "skips": 0,
           "todos": 0
         },
+        "a-refusal-marks-the-field-in-whichever-view-is-open.test.mjs": {
+          "tests": 4,
+          "asserts": 10,
+          "skips": 0,
+          "todos": 0
+        },
         "a-refusal-means-nothing-without-its-control.test.mjs": {
           "tests": 8,
           "asserts": 38,
@@ -1216,8 +1222,8 @@
           "todos": 0
         },
         "bundle-rebuild-and-ports.test.mjs": {
-          "tests": 7,
-          "asserts": 17,
+          "tests": 10,
+          "asserts": 24,
           "skips": 0,
           "todos": 0
         },
@@ -1288,8 +1294,8 @@
           "todos": 0
         },
         "channel-fallback-silence.test.mjs": {
-          "tests": 6,
-          "asserts": 18,
+          "tests": 9,
+          "asserts": 28,
           "skips": 0,
           "todos": 0
         },
@@ -1337,7 +1343,7 @@
         },
         "client-door.test.mjs": {
           "tests": 38,
-          "asserts": 162,
+          "asserts": 163,
           "skips": 1,
           "todos": 0
         },
@@ -1432,8 +1438,8 @@
           "todos": 0
         },
         "connect-clients-are-data.test.mjs": {
-          "tests": 15,
-          "asserts": 75,
+          "tests": 17,
+          "asserts": 87,
           "skips": 0,
           "todos": 0
         },
@@ -1870,8 +1876,8 @@
           "todos": 0
         },
         "doctor-reads-the-units-not-the-shell.test.mjs": {
-          "tests": 33,
-          "asserts": 96,
+          "tests": 37,
+          "asserts": 111,
           "skips": 1,
           "todos": 0
         },
@@ -2092,8 +2098,8 @@
           "todos": 0
         },
         "engine.anthropic.test.mjs": {
-          "tests": 61,
-          "asserts": 222,
+          "tests": 65,
+          "asserts": 238,
           "skips": 0,
           "todos": 0
         },
@@ -2368,8 +2374,8 @@
           "todos": 0
         },
         "form-neighbourhood.test.mjs": {
-          "tests": 17,
-          "asserts": 68,
+          "tests": 20,
+          "asserts": 89,
           "skips": 0,
           "todos": 0
         },
@@ -2704,8 +2710,8 @@
           "todos": 0
         },
         "matter-frame-record.test.mjs": {
-          "tests": 12,
-          "asserts": 48,
+          "tests": 20,
+          "asserts": 71,
           "skips": 0,
           "todos": 0
         },
@@ -2818,8 +2824,8 @@
           "todos": 0
         },
         "nothing-a-command-awaits-imports-it-back.test.mjs": {
-          "tests": 16,
-          "asserts": 49,
+          "tests": 18,
+          "asserts": 56,
           "skips": 0,
           "todos": 0
         },
@@ -3058,8 +3064,8 @@
           "todos": 0
         },
         "portal-access.test.mjs": {
-          "tests": 13,
-          "asserts": 50,
+          "tests": 16,
+          "asserts": 59,
           "skips": 0,
           "todos": 0
         },
@@ -3250,8 +3256,8 @@
           "todos": 0
         },
         "profiles.test.mjs": {
-          "tests": 43,
-          "asserts": 241,
+          "tests": 48,
+          "asserts": 263,
           "skips": 0,
           "todos": 0
         },
@@ -3310,8 +3316,8 @@
           "todos": 0
         },
         "purge-runs.test.mjs": {
-          "tests": 19,
-          "asserts": 47,
+          "tests": 25,
+          "asserts": 71,
           "skips": 0,
           "todos": 0
         },
@@ -3520,8 +3526,8 @@
           "todos": 0
         },
         "register-capabilities.test.mjs": {
-          "tests": 33,
-          "asserts": 263,
+          "tests": 34,
+          "asserts": 268,
           "skips": 0,
           "todos": 0
         },
@@ -4348,8 +4354,8 @@
           "todos": 0
         },
         "symbol-citation-survives-a-move.test.mjs": {
-          "tests": 8,
-          "asserts": 18,
+          "tests": 9,
+          "asserts": 25,
           "skips": 0,
           "todos": 0
         },
@@ -4426,8 +4432,8 @@
           "todos": 0
         },
         "test-run-tmpdir.test.mjs": {
-          "tests": 11,
-          "asserts": 25,
+          "tests": 12,
+          "asserts": 27,
           "skips": 0,
           "todos": 0
         },
@@ -4475,7 +4481,7 @@
         },
         "the-boot-line-says-which-door-it-found.test.mjs": {
           "tests": 5,
-          "asserts": 21,
+          "asserts": 26,
           "skips": 0,
           "todos": 0
         },
@@ -4570,8 +4576,8 @@
           "todos": 0
         },
         "the-demo-offers-no-background-form.test.mjs": {
-          "tests": 4,
-          "asserts": 14,
+          "tests": 5,
+          "asserts": 19,
           "skips": 0,
           "todos": 0
         },
@@ -4756,8 +4762,8 @@
           "todos": 0
         },
         "the-minters-read-the-published-tree.test.mjs": {
-          "tests": 2,
-          "asserts": 6,
+          "tests": 4,
+          "asserts": 12,
           "skips": 0,
           "todos": 0
         },
@@ -4774,14 +4780,14 @@
           "todos": 0
         },
         "the-notice-goes-to-whoever-asked.test.mjs": {
-          "tests": 8,
-          "asserts": 23,
+          "tests": 10,
+          "asserts": 28,
           "skips": 1,
           "todos": 0
         },
         "the-open-line-says-what-to-do-when-the-page-is-not-ours.test.mjs": {
-          "tests": 4,
-          "asserts": 13,
+          "tests": 6,
+          "asserts": 24,
           "skips": 0,
           "todos": 0
         },
@@ -5037,6 +5043,12 @@
           "skips": 0,
           "todos": 0
         },
+        "the-trigger-reaches-a-local-socket.test.mjs": {
+          "tests": 4,
+          "asserts": 24,
+          "skips": 0,
+          "todos": 0
+        },
         "the-two-env-files-are-named-where-they-appear.test.mjs": {
           "tests": 5,
           "asserts": 12,
@@ -5493,8 +5505,8 @@
           "todos": 0
         },
         "cf-access.test.mjs": {
-          "tests": 18,
-          "asserts": 28,
+          "tests": 20,
+          "asserts": 34,
           "skips": 0,
           "todos": 0
         },
@@ -5511,8 +5523,8 @@
           "todos": 0
         },
         "connector-guidance.test.mjs": {
-          "tests": 11,
-          "asserts": 65,
+          "tests": 13,
+          "asserts": 70,
           "skips": 0,
           "todos": 0
         },
@@ -5619,8 +5631,8 @@
           "todos": 0
         },
         "ops.test.mjs": {
-          "tests": 38,
-          "asserts": 164,
+          "tests": 39,
+          "asserts": 168,
           "skips": 0,
           "todos": 0
         },
@@ -5637,8 +5649,8 @@
           "todos": 0
         },
         "plan.test.mjs": {
-          "tests": 26,
-          "asserts": 112,
+          "tests": 28,
+          "asserts": 125,
           "skips": 0,
           "todos": 0
         },
@@ -5852,8 +5864,8 @@
           "todos": 0
         },
         "home.test.ts": {
-          "tests": 46,
-          "asserts": 141,
+          "tests": 51,
+          "asserts": 169,
           "skips": 0,
           "todos": 0
         },
@@ -6078,8 +6090,8 @@
           "todos": 0
         },
         "providers/_shared/test/count-kernel.test.mjs": {
-          "tests": 8,
-          "asserts": 36,
+          "tests": 10,
+          "asserts": 45,
           "skips": 0,
           "todos": 0
         },
@@ -6150,8 +6162,14 @@
           "todos": 0
         },
         "providers/_shared/test/territory-codes.test.mjs": {
-          "tests": 9,
-          "asserts": 25,
+          "tests": 11,
+          "asserts": 38,
+          "skips": 0,
+          "todos": 0
+        },
+        "providers/clarivate/test/phrase-value.test.mjs": {
+          "tests": 6,
+          "asserts": 23,
           "skips": 0,
           "todos": 0
         },

package/mcp-server/CHANGELOG.md

@@ -1,5 +1,17 @@
 # trademark-artifacts-mcp
 
+## 0.3.1-beta.2
+
+### Patch Changes
+
+- f96c089: Fixed: A clearance for a new client can be ordered through an assistant connector without setting up a company first.
+- 240673c: Fixed: Sending an access key to the engine's network address now gets a refusal that says so. It reports that the address takes an identity from the sign-in proxy and never a key.
+  
+  Fixed: That refusal also names the local door where a key is accepted. Before, it reported only a missing sign-in assertion, which sent operators to the wrong configuration.
+  
+  For operators: A program on the same machine can now reach the engine's local key door without setting a host name for it. The local door no longer applies a browser protection that only a network address needs.
+- f96c089: New: The free preview of a search lists, for each territory ordered, which registers legally bind it.
+
 ## 0.3.1-beta.1
 
 No changes in this release.

package/mcp-server/http-server.mjs

@@ -128,14 +128,31 @@ const LOOPBACK = new Set(["127.0.0.1", "::1"]);
 // transport is imported lazily here (it pulls @hono/node-server/undici) so nothing else has to.
 // `owner` = the authed email that created the session; stored on the entry so the handler can refuse a
 // different identity attaching to it (session owner-binding).
-async function createSession(sessions, scope = { kind: "internal", runId: null }, owner = null) {
+// ── DNS-REBINDING PROTECTION BELONGS TO THE NETWORK DOOR, AND ONLY TO IT ────────────────────────────
+//
+// `networkDoor` is false for the key socket. Both doors share this factory, and the allowed-hosts list
+// it arms is read from the TCP door's own environment — so a socket caller was being held to a Host
+// header naming the TCP door's address, on a transport that has no host, no port and no DNS.
+//
+// key-socket.mjs already states in terms that this refusal does not apply to 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." That was true of the door it builds and false of the sessions that door
+// creates, because the exclusion lived in a comment beside one handler while the protection lived in
+// the factory both handlers call. Measured on a real key over a real socket: the call succeeds ONLY if
+// the caller sends a Host naming the TCP listener, which is a requirement nothing documents and no
+// integrator would guess.
+//
+// The network door is UNCHANGED — it passes nothing and keeps the default — so this narrows one
+// transport rather than relaxing a protection.
+async function createSession(sessions, scope = { kind: "internal", runId: null }, owner = null,
+                             { networkDoor = true } = {}) {
   const { StreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/streamableHttp.js");
   // HTTP is never the trusted-local surface: local:false (so what-if is never exposed remotely, even to ops).
   const server = makeServer({ scope, local: false });
   const transport = new StreamableHTTPServerTransport({
     sessionIdGenerator: () => randomUUID(),
-    enableDnsRebindingProtection: ALLOWED_HOSTS.length > 0,
-    allowedHosts: ALLOWED_HOSTS.length ? ALLOWED_HOSTS : undefined,
+    enableDnsRebindingProtection: networkDoor && ALLOWED_HOSTS.length > 0,
+    allowedHosts: networkDoor && ALLOWED_HOSTS.length ? ALLOWED_HOSTS : undefined,
     onsessioninitialized: (id) => sessions.set(id, { server, transport, lastSeen: Date.now(), email: owner, sub: scope?.sub ?? null, kind: scope?.kind ?? null }),
   });
   transport.onclose = () => { if (transport.sessionId) sessions.delete(transport.sessionId); };
@@ -303,6 +320,9 @@ if (isMain) {
   // non-firm identity a mis-scoped edge might admit. Tenants gated purely by MCP_ALLOWED_EMAILS leave this
   // list empty, so tokenless internal read-all stays off for them (fail-closed) unless they set the domain list.
   const handler = makeHttpHandler({ verify, limiter, opsLimiter, sessions, createSession, ns: NS, sessionMax: SESSION_MAX,
+    // The network door tells a caller who sends a key WHERE the key door is, when this deployment has
+    // one. Refusing without saying that is what sent the last operator to the proxy's configuration.
+    keyDoorPath: KEY_SOCKET || null,
     authHeader: AUTH_HEADER, devMode: !TOKEN_ONLY && AUTH_DISABLED && DEV, tokenOnly: TOKEN_ONLY, firmDomains: ALLOWED_DOMAINS, log });
   // Three states now, and the line must name the one it is in. "AUTH OFF (dev)" was printed by anything
   // with a null `verify`, which from here on includes the key door — a line claiming the opposite of
@@ -337,7 +357,10 @@ if (isMain) {
     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,
+      limiter, opsLimiter, sessions: new Map(), ns: NS, sessionMax: SESSION_MAX,
+      // The socket's sessions are not network sessions — see createSession. Passed here rather than
+      // read inside it, so the factory keeps one rule and the caller names which door it is.
+      createSession: (sessions, scope, owner) => createSession(sessions, scope, owner, { networkDoor: false }),
       authHeader: AUTH_HEADER, firmDomains: ALLOWED_DOMAINS, log,
     });
     openKeyDoor({ handler: keyHandler, path: KEY_SOCKET, log })

package/mcp-server/lib/cf-access.mjs

@@ -34,7 +34,7 @@ export class AuthError extends Error {
  * applied IN ADDITION to the domain gate (either empty list = that gate off). Building a verifier with
  * NO identity gate at all requires an explicit allowAnyDomain:true (fail-closed footgun guard).
  */
-export function makeAccessVerifier({ team, aud, allowedDomains = [], allowedEmails = [], allowAnyDomain = false, identityMode = "intersection", issuer, jwksUrl, emailClaim = "email", jwks } = {}) {
+export function makeAccessVerifier({ team, aud, allowedDomains = [], allowedEmails = [], allowedNow = null, allowAnyDomain = false, identityMode = "intersection", issuer, jwksUrl, emailClaim = "email", jwks } = {}) {
   const iss = issuer || (team ? `https://${team}.cloudflareaccess.com` : "");
   // `!aud` alone does not close this: an EMPTY ARRAY is truthy, so a parser that returned `[]` for an
   // unset variable would satisfy this guard and the four call sites' `!AUD` at once. MEASURED, because
@@ -94,7 +94,21 @@ export function makeAccessVerifier({ team, aud, allowedDomains = [], allowedEmai
     if (identityMode === "union") {
       const okDomain = domains.length > 0 && domains.includes(domain);
       const okEmail = emails.length > 0 && emails.includes(email);
-      if (!okDomain && !okEmail) throw new AuthError(403, `email not permitted: ${email}`);
+      // ── AND THE PEOPLE THE DEPLOYMENT HAS ADDED SINCE THIS VERIFIER WAS BUILT ──────────────────────
+      //
+      // The two lists above are read once, at construction, out of the environment. The People page
+      // writes a person into the deployment's own guest list and the write succeeds — and this check
+      // never saw it, so the person was refused at the door with a 403 naming their address, and no
+      // restart helped because the values do not come from the file they were added to. Somebody added
+      // on the page could not sign in, which is the page's whole promise.
+      //
+      // ASKED AT VERIFY TIME, not frozen: `allowedNow` is a callback the caller supplies, reading the
+      // guest list as it is now. It can only ADD — the env lists stay exactly as they were, so a
+      // deployment that names nobody in a file is not widened by this and the fail-closed guards above
+      // still decide whether a verifier may be built at all.
+      const okAdded = !okDomain && !okEmail && typeof allowedNow === "function"
+        && (() => { try { return allowedNow().includes(email); } catch { return false; } })();
+      if (!okDomain && !okEmail && !okAdded) throw new AuthError(403, `email not permitted: ${email}`);
     } else {
       if (domains.length && !domains.includes(domain)) throw new AuthError(403, `email domain not permitted: ${email}`);
       if (emails.length && !emails.includes(email)) throw new AuthError(403, `email not on the allowlist: ${email}`);

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

@@ -69,7 +69,7 @@ export function evictOldest(sessions) {
  * presents another identity's mcp-session-id is refused (403) — a leaked/guessed session id must never
  * let one CF-authed person attach to another's session (which may carry an ops-scoped inner token).
  */
-export function makeHttpHandler({ verify, limiter, opsLimiter = null, sessions, createSession, ns = "trademark-artifacts", sessionMax = 500, maxBody = 4 * 1024 * 1024, authHeader = "cf-access-jwt-assertion", firmDomains = [], clientSurface = false, devMode = false, tokenOnly = false, log = () => {} }) {
+export function makeHttpHandler({ verify, limiter, opsLimiter = null, sessions, createSession, ns = "trademark-artifacts", sessionMax = 500, maxBody = 4 * 1024 * 1024, authHeader = "cf-access-jwt-assertion", firmDomains = [], clientSurface = false, devMode = false, tokenOnly = false, keyDoorPath = null, log = () => {} }) {
   if (!verify && !devMode && !tokenOnly) throw new Error("makeHttpHandler: verify is required unless devMode:true or tokenOnly:true (fail-closed; refusing to build an unauthenticated handler)");
   // The two verify-less modes mean OPPOSITE things and must never be combined: devMode trusts the local
   // operator and hands out a synthetic identity, tokenOnly trusts NOBODY without a valid key. Together,
@@ -99,6 +99,42 @@ export function makeHttpHandler({ verify, limiter, opsLimiter = null, sessions,
           user = await verify(hdr(req.headers[authHeader]));
         } catch (e) {
           const status = e instanceof AuthError ? e.status : 401;
+          // ── A KEY PRESENTED HERE IS NOT A MISSING JWT, AND THE OLD SENTENCE SAID IT WAS ─────────
+          //
+          // This door takes a proxy identity and has no path that reads an access key — the refusal is
+          // structural rather than a check. But the sentence a caller got was "missing auth-proxy JWT",
+          // which is a statement about an ABSENT assertion and says nothing about the key that was
+          // actually sent. Measured against a real key on all three carriers: an operator reads it as a
+          // misconfigured proxy and goes looking there. That is the outage this issue was raised from
+          // wearing a different hat — a true sentence that is not the one the reader needs.
+          //
+          // DETECTED ON THE UNAMBIGUOUS CARRIERS ONLY. `?token=` and `x-trademark-token` carry nothing
+          // but a trademark key. `Authorization` is NOT read here even though a key can arrive in it,
+          // because on a proxy-fronted door that header belongs to whatever the proxy or agent is doing
+          // and reading it as a key would put this sentence in front of callers who never sent one. So
+          // a key in `Authorization` still gets the old message: narrower than the finding, and wrong
+          // in the direction that costs nothing.
+          const keySent = e instanceof AuthError && e.status === 401
+            && Boolean(url.searchParams.get("token") || hdr(req.headers["x-trademark-token"]));
+          if (keySent) {
+            log("auth reject 401: an access key was presented on the proxy door, which has no key path");
+            // THE SENTENCE IS ALSO READ BY A MACHINE, and the first draft of it broke that. `doorCredential`
+            // in shared/trigger-lane.mjs classifies a door by what its refusal asks for, and the portal's
+            // boot probe uses that to report which lane it has. A sentence saying "an access key has no
+            // door here" contains the words "access key", so it classified as a KEY door — and the portal
+            // would have announced that the network door takes its key, against a door that refuses it.
+            // That is this issue's own false-reassurance finding, reintroduced by the fix for its
+            // neighbour. Naming the JWT puts it in the proxy branch, which is checked first and is the
+            // true answer: this door wants a proxy identity.
+            // THE PATH IS NOT IN THE SENTENCE, and the first draft put it there. This door faces the
+            // internet and answers before anyone has authenticated, so naming the socket's filesystem
+            // path hands an unauthenticated stranger a piece of the deployment's layout. They cannot
+            // reach it — the protection is the filesystem — so it is disclosure rather than exposure,
+            // and it buys nothing: an operator needs to know a local socket is where to look, and
+            // already has the path in the boot line and the unit file. A stranger gets nothing usable.
+            return send(res, 401, { error: "this listener takes an auth-proxy JWT and never an access key — a key has no door here"
+              + (keyDoorPath ? ". A key is taken on this deployment's local socket; the engine's boot line names it" : ". This deployment has no key door configured") });
+          }
           log(`auth reject ${status}: ${e.message}`);
           return send(res, status, { error: e.message });
         }

package/mcp-server/lib/ops.mjs

@@ -17,7 +17,7 @@ import { validateJob } from "../../driver/enqueue-schema.mjs";
 import { doorGates } from "../../driver/door-gates.mjs";   // the resolved-product checks every door runs
 import { probeQueueWatch, unwatchedQueueWarning } from "../../driver/queue-watch-probe.mjs";   //
 import { resolveRun, runAccountKey } from "./runs.mjs";
-import { assertAccountAccess, attributionOf } from "../../shared/scope.mjs";
+import { assertAccountAccess, attributionOf, grantsGeneric, GENERIC_NOT_GRANTED } from "../../shared/scope.mjs";
 import { requestCancel, isCancelled } from "../../driver/cancel.mjs";   // one marker shape, shared with the engine
 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
@@ -224,20 +224,33 @@ export const START_RUN_JOB_FIELDS = Object.freeze({
   }),
 });
 
-// The accounts-scoped rule shared by start_run and plan_run: name the account EXPLICITLY. The grant gate
-// keys on profileKey, but the runner's forwarderDomain→matchDomains fallback could resolve a FOREIGN
-// customer for an untagged job — closing the bypass at the door. plan_run enforces it
-// too so a scoped caller cannot use the free preview to probe another customer's configuration.
-export function assertScopedProfileKey(args, scope, verb) {
-  if (Array.isArray(scope?.accounts) && !(args.profileKey && String(args.profileKey).trim()))
-    throw new Error(`${verb}: an accounts-scoped session must set profileKey explicitly (domain-based customer resolution is not available to scoped tokens)`);
+// The accounts-scoped rule shared by start_run and plan_run: the job must NAME the account it runs
+// under. The grant gate keys on profileKey, but the runner's forwarderDomain→matchDomains fallback could
+// resolve a FOREIGN customer for an untagged job — so an untagged job is what the door refuses to build.
+// plan_run goes through it too, so a scoped caller cannot use the free preview to probe another
+// customer's configuration.
+//
+// NAMING IT IS NOT THE SAME AS THE CALLER TYPING IT, and reading the two as one refused the ordinary
+// case this door exists to serve. A clearance for a NEW client has no account yet; the connector's own
+// instructions say to omit profileKey then, and this threw on exactly that, so an assistant following
+// its briefing hit a wall it could not explain. Where the session's access covers Generic, the neutral
+// profile a job with no profileKey runs under anyway, the door now writes that key into the job itself:
+// the bypass stays closed because the job is tagged, and the caller gets the run they asked for.
+//
+// Where it does not, the refusal says what to do next instead of only what is forbidden.
+export function resolveScopedProfileKey(args, scope, verb) {
+  if (!Array.isArray(scope?.accounts)) return args;
+  if (args.profileKey && String(args.profileKey).trim()) return args;
+  if (grantsGeneric(scope)) return { ...args, profileKey: "generic" };
+  throw new Error(`${verb}: this session holds [${scope.accounts.join(", ")}] and the request names no account. `
+    + `${GENERIC_NOT_GRANTED} A job that names no customer is never resolved from the requester's email domain.`);
 }
 
 // start_run — enqueue a clearotron job the runner will drain. Returns the queue id + slug; the runId/codename is
 // assigned by the runner on claim, so the caller polls list_runs(slug) / run_changes for it.
 export function startRun(args = {}, { scope } = {}) {
   const agent = args.agent ? String(args.agent) : "";
-  assertScopedProfileKey(args, scope, "start_run");
+  args = resolveScopedProfileKey(args, scope, "start_run");
   const qdir = queueDir(agent);
   // ONE builder shared with plan_run, so the preview a caller confirms is the job that actually runs.
   let job;

package/mcp-server/lib/options.mjs

@@ -331,7 +331,7 @@ export function describeOptions(args = {}, { scope, now = Date.now() } = {}) {
   const account = accountFor(key, { scope, now });
   const granted = scope?.accounts;
   // The profileKey discovery answer: several accounts held, none named. Listing the KEYS (and, where the
-  // roster reads, their names) is what turns "an accounts-scoped session must set profileKey explicitly"
+  // roster reads, their names) is what turns "this session holds [...] and the request names no account"
   // from a dead end into a question the assistant can put to its user.
   const accountsGranted = !account && Array.isArray(granted) && granted.length
     ? granted.map((k) => {

package/mcp-server/lib/plan.mjs

@@ -34,8 +34,10 @@ import { gateResolvedRequest } from "../../driver/door-gates.mjs";   // the reso
 import { quoteForJob } from "../../driver/run-quote.mjs";
 import { accountUsage, DEFAULT_CLIENT_DAILY_RUNS } from "../../driver/usage-ledger.mjs";
 import { config } from "./driver.mjs";
-import { buildJob, assertScopedProfileKey } from "./ops.mjs";
+import { buildJob, resolveScopedProfileKey } from "./ops.mjs";
 import { BRAND } from "../../shared/brand.mjs";   // — the operator name in the allowance note, from the tenant seam
+import { bindingLayersFor } from "../../driver/binding-layers.mjs";   // — what BINDS a territory; never what a provider returns
+import { normalizeTerritory } from "../../providers/_shared/territory-codes.mjs";
 
 // The verbatim legal caveat every plan carries. NOT paraphrasable: it states what a common-law-first
 // screen can and cannot tell you, and softening it would misrepresent the product to the person deciding
@@ -141,13 +143,52 @@ function allowanceFor(profile, { scope, now = Date.now() } = {}) {
   };
 }
 
+/**
+ * WHICH REGISTERS ALREADY BIND EACH ORDERED TERRITORY, for the preview to say out loud.
+ *
+ * A requester asked to clear a mark in one EU member state and was sold the member state AND the EU as
+ * two territories, on the reasoning that the EU-wide right had to be listed to be covered. It does not:
+ * an EU trade mark blocks use in the member state without appearing in its national register, and the
+ * engine has searched on that basis since the ruling `binding-layers.mjs` quotes in its header. Naming
+ * two territories instead resolves a different product — the one that carries no case-law reading and
+ * no automatic native-language investigation — so the composition bought less coverage for more money,
+ * and nothing on this surface said so.
+ *
+ * WHAT BINDS A TERRITORY, NOT WHAT A SEARCH RETURNS. `binding-layers.mjs` separates those two facts
+ * deliberately: the first is a property of the territory and always true, the second is a vendor fact
+ * that is often unestablished. This reports the first only. `search.registerReach` next to it is the
+ * second, and the two must never be blurred into one sentence.
+ *
+ * A territory this build cannot resolve to a register says so rather than being dropped from the list:
+ * a silent omission reads as "nothing binds there", which is never true.
+ */
+function bindingLayersForOrder(jurisdictions) {
+  const out = [];
+  for (const j of jurisdictions ?? []) {
+    const code = normalizeTerritory(j);
+    if (!code) {
+      out.push({ territory: j, code: null, binds: null,
+        note: `"${j}" could not be matched to a register this build knows, so what binds it is not stated here` });
+      continue;
+    }
+    try {
+      out.push({ territory: j, code, binds: bindingLayersFor(code).map((b) => ({ layer: b.layer, office: b.office, why: b.why })) });
+    } catch {
+      out.push({ territory: j, code, binds: null, note: `what binds "${j}" could not be read` });
+    }
+  }
+  return out;
+}
+
 /**
  * plan_run — resolve a prospective search and describe it. Spends nothing, writes nothing.
  *
  * Takes the SAME args as start_run. Confirming is a separate, explicit start_run call with the same args.
  */
 export function planRun(args = {}, { scope, now = Date.now() } = {}) {
-  assertScopedProfileKey(args, scope, "plan_run");
+  // Resolved, not merely checked — and BEFORE buildJob, so the preview describes the job start_run
+  // would build, including the account it would run under when the request named none.
+  args = resolveScopedProfileKey(args, scope, "plan_run");
   // The EXACT job start_run would build — not a lookalike assembled here, which could drift from it.
   const job = buildJob(args, { scope });
 
@@ -352,6 +393,10 @@ export function planRun(args = {}, { scope, now = Date.now() } = {}) {
     scope: {
       jurisdictions: eff.jurisdictions,
       jurisdictionsFrom: eff.jurisdictionsFrom,
+      // WHAT EACH ORDERED TERRITORY ALREADY BINDS — so nobody adds a region to the list to "include"
+      // a right that the country already carries, and pays for it with the product that change
+      // resolves to. This is the territory's own property, never a claim about what the search returns.
+      bindingLayers: bindingLayersForOrder(eff.jurisdictions),
       platforms: eff.platforms,
       platformsAdded: eff.platformsAdded,
       platformsFrom: eff.platformsFrom,

package/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trademark-artifacts-mcp",
-  "version": "0.3.1-beta.1",
+  "version": "0.3.1-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.",