@everfur/cli 0.2.1 → 0.5.0

package/dist/{chunk-FC23PLWG.js → chunk-KAHIDPBX.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { buildServer } from './chunk-XMIERMOW.js';
+import { buildServer } from './chunk-IZGEY7H6.js';
 import { createServer } from 'http';
 import { timingSafeEqual } from 'crypto';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';

package/dist/{chunk-4UB26D67.js → chunk-NLB5XDNO.js}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, offlineSuggestions, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, knownCodes, buildExplanationDocument, renderExplanation, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, buildSdkExplanationDocument, renderSdkExplanation, buildContractTableExplanationDocument, renderContractTableExplanation, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-KQICUK54.js';
+import { VERIFY_IDENTITY_MODES, SURFACES, ENVIRONMENTS, BASE_URL_ENV_VAR, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ALL_CAPABILITIES, expandCapabilities, errorOutcome, describeFailure, failureDetails, countsAsNotOn, diagnoseVerdict, isJsonObject, succeed, CAPABILITY_QUESTION, CAPABILITIES_TREE, WEB_EMBEDDING_QUESTION, PLATFORM_TREE, loadDecisionSpace, fetchContract, contractUnavailableOutcome, loadDecisionSpaceFromContract, parseEnvironment, checkTenantMode, detectProject, planIntegration, fail, ExitCode, DOCS_KEY, resolveContractPath, validateContractFile, buildSupportBundle, renderSupportBundle, chooseWidgetAuth, DIAGNOSTICS_PATH, diagnoseFailure, parseDiagnostics, buildDiagnosisDocument, PARTNER_KEY, SESSION_TOKEN, resolveCredential, ADMIN_TOKEN, withPrefix, parseOrigin, parseLoaderUrl, parseSurfaces, parseIdentityMode, runVerification, PARTNER_SECRET_KEY, resolveOffline, resolveWithoutRegistry, knownCodes, loadErrorRegistryFromContract, loadErrorRegistry, resolveAfterRegistryMiss, registryAlsoIn, buildExplanationDocument, renderExplanation, alsoInLines, resolveEndpoint, isCorrelatableRequestId, EMPTY_REGISTRY, createApiClient, offlineDocument, renderOffline, IDENTITY_QUESTION, IDENTITY_TREE, BACKEND_LANGUAGE_QUESTION, SESSION_MINT_TREE, CREDENTIAL_SPECS } from './chunk-CGWSEOW2.js';
 import { isAbsolute, resolve } from 'path';
 
 // src/cli/format.ts
@@ -186,6 +186,9 @@ function renderRefusal(document) {
     lines.push(`  ${fact.fact}`);
     lines.push(`    why:    ${fact.reason}`);
     lines.push(`    supply: ${fact.supplyWith}`);
+    if (fact.requiredWhen !== void 0) {
+      lines.push(`    only when: ${fact.requiredWhen.fact} is ${fact.requiredWhen.oneOf.join(" or ")}; answer it with that fact`);
+    }
   }
   lines.push("");
   lines.push(...renderDetected(document));
@@ -523,6 +526,14 @@ var CONTRACT_FLAG = Object.freeze({
   summary: "Path to a contract-public projection, used to explain any error code returned.",
   placeholder: "file"
 });
+var PLAN_CONTRACT_FLAG = Object.freeze({
+  ...CONTRACT_FLAG,
+  summary: "Path to a contract-public projection to plan from (its decision trees), read instead of the contract fetched with EVERFUR_DOCS_KEY."
+});
+var EXPLAIN_CONTRACT_FLAG = Object.freeze({
+  ...CONTRACT_FLAG,
+  summary: "Path to a contract-public projection whose error registry answers the code, read instead of the contract fetched with EVERFUR_DOCS_KEY."
+});
 var CONTRACT_ENV_VAR = "EVERFUR_CONTRACT_PUBLIC";
 var DEFAULT_CONTRACT_PATHS = Object.freeze([
   "contract-public/contract-public.json",
@@ -613,6 +624,7 @@ var POLL_DELAY_MS = 500;
 var MAX_ATTEMPTS = 20;
 var VERIFICATION_SCHEMA_VERSION = 1;
 var VERIFICATION_DOCUMENT_KIND = "everfur.verification";
+var WEB_EMBEDDINGS = Object.freeze(["in-page", "frame"]);
 var FLAGS = Object.freeze([
   BASE_URL_FLAG,
   {
@@ -630,9 +642,16 @@ var FLAGS = Object.freeze([
   {
     name: "origin",
     kind: "string",
-    summary: "For a web integration: the page origin (https://shop.example.com) the surface is embedded on. Adds the embed fence, CORS exposure, session policy and loader checks.",
+    summary: "For a framed web page (the loader and an iframe): the page origin (https://shop.example.com) the frame renders on. Adds the CORS preflight, embed fence, CORS exposure, session policy and loader checks. An in-page integration needs no --origin.",
     placeholder: "origin"
   },
+  {
+    // The same flag name `plan` takes for the same fact (the argv parser knows it as a value flag).
+    name: "embedding",
+    kind: "string",
+    summary: `With --origin: how the page embeds the surface, ${WEB_EMBEDDINGS.join(" or ")}. frame (the default without --project-root) runs every check; in-page (the SDK's React components in the page) reports the embed fence and the loader N/A, since only the frame uses them. Read from --project-root when not given.`,
+    placeholder: "mode"
+  },
   {
     name: "loader-url",
     kind: "string",
@@ -665,10 +684,12 @@ var FLAGS = Object.freeze([
 function buildVerificationDocument(verification, baseUrl, cliVersion) {
   const counts = { passed: 0, failed: 0, skipped: 0 };
   let gated = 0;
+  let notApplicable = 0;
   for (const entry of verification.steps) {
     if (entry.result === "PASS") counts.passed += 1;
     else if (entry.result === "FAIL") counts.failed += 1;
     else if (entry.result === "GATED") gated += 1;
+    else if (entry.result === "N/A") notApplicable += 1;
     else counts.skipped += 1;
   }
   return {
@@ -677,8 +698,9 @@ function buildVerificationDocument(verification, baseUrl, cliVersion) {
     generatedBy: { name: "@everfur/cli", version: cliVersion },
     status: verification.status,
     baseUrl,
-    // `gated` appears only when a step was GATED, so a document from a run with no surface checks is unchanged.
-    summary: gated === 0 ? counts : { ...counts, gated },
+    // `gated` appears only when a step was GATED, and `notApplicable` only when one was N/A, so a document from a run
+    // with neither is unchanged.
+    summary: { ...counts, ...gated === 0 ? {} : { gated }, ...notApplicable === 0 ? {} : { notApplicable } },
     steps: verification.steps.map((entry) => ({
       id: entry.id,
       title: entry.title,
@@ -709,6 +731,8 @@ function renderVerification(verification, baseUrl) {
     lines.push("Nothing failed, but a step was skipped, so the wire was not fully exercised.");
   } else if (verification.steps.some((entry) => entry.result === "GATED")) {
     lines.push("Nothing failed. A GATED step is a surface Everfur has not switched on for this tenant, not a fault in the integration.");
+  } else if (verification.steps.some((entry) => entry.result === "N/A")) {
+    lines.push("Nothing failed. An N/A step is a check that does not apply to this integration, and it was not run.");
   } else {
     lines.push(
       verification.steps.some((entry) => entry.id === "anonymous-identity") ? "Every step passed. The anonymous identity, the verdict read, and the verdict itself are all healthy." : "Every step passed. The session mint, the verdict read, and the verdict itself are all healthy."
@@ -716,6 +740,12 @@ function renderVerification(verification, baseUrl) {
   }
   return lines.join("\n");
 }
+function parseEmbedding2(raw) {
+  if (raw === null) return { value: null, errors: [] };
+  const value = raw.trim();
+  const known2 = WEB_EMBEDDINGS.find((embedding) => embedding === value);
+  return known2 === void 0 ? { value: null, errors: [`--embedding must be ${WEB_EMBEDDINGS.join(" or ")}, not "${raw}"`] } : { value: known2, errors: [] };
+}
 function parseAttempts(raw) {
   if (raw === null) return { value: DEFAULT_ATTEMPTS, errors: [] };
   const parsed = Number(raw.trim());
@@ -730,7 +760,7 @@ function parseAttempts(raw) {
 var verifyCommand = {
   path: ["verify"],
   summary: "Exercise the wire: mint a session, read the verdict, assert it is not empty.",
-  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
+  usage: "verify [--base-url <url>] [--user-ref <ref>] [--attempts <n>] [--identity <mode>] [--origin <origin>] [--embedding <mode>] [--loader-url <url>] [--surfaces <list>] [--project-root <path>] [--json]",
   flags: FLAGS,
   /**
    * Exactly what `mintSession` resolves: the session token first, else the key pair it mints with locally. Without
@@ -741,6 +771,7 @@ var verifyCommand = {
     const attempts = parseAttempts(flags.string("attempts"));
     const originFlag = flags.string("origin");
     const origin = originFlag === null ? { origin: null, error: null } : parseOrigin(originFlag);
+    const embedding = parseEmbedding2(flags.string("embedding"));
     const loaderFlag = flags.string("loader-url");
     const loader = loaderFlag === null ? { url: null, error: null } : parseLoaderUrl(loaderFlag);
     const surfaces = parseSurfaces(flags.string("surfaces"));
@@ -751,6 +782,7 @@ var verifyCommand = {
     const flagErrors = [
       ...attempts.errors,
       ...origin.error === null ? [] : [origin.error],
+      ...embedding.errors,
       ...loader.error === null ? [] : [loader.error],
       ...surfaces.errors,
       ...identityMode.errors,
@@ -771,6 +803,7 @@ var verifyCommand = {
       attempts: attempts.value,
       pollDelayMs: POLL_DELAY_MS,
       origin: origin.origin,
+      embedding: embedding.value,
       loaderUrl: loader.url,
       transport: context.transport,
       surfaces: surfaces.value ?? [],
@@ -826,7 +859,7 @@ var FLAGS2 = Object.freeze([
     summary: `The Everfur deployment the generated configuration targets: ${ENVIRONMENTS.join(", ")}. Required for a plan that writes configuration; never assumed.`,
     placeholder: "name"
   },
-  CONTRACT_FLAG
+  PLAN_CONTRACT_FLAG
 ]);
 function asJsonObject(document) {
   return JSON.parse(JSON.stringify(document));
@@ -912,8 +945,10 @@ var planCommand = {
         ...environment.errors
       ]);
     }
+    const mode = await checkTenantMode({ env: context.env, environment: environment.value, transport: context.transport, clock: context.clock });
+    if (mode.kind === "mismatch") return errorOutcome("usage_error", mode.message, mode.details);
     const detection = detectProject(context.fs, root);
-    const document = planIntegration({
+    const planned = planIntegration({
       detection,
       capabilities: supplied.capabilities,
       allCapabilities: supplied.allCapabilities,
@@ -924,6 +959,7 @@ var planCommand = {
       space,
       cliVersion: context.version
     });
+    const document = mode.kind === "not_checked" && planned.status === "ready" ? Object.freeze({ ...planned, warnings: Object.freeze([...planned.warnings, mode.warning]) }) : planned;
     const json = asJsonObject(document);
     const text = renderPlan(document);
     if (document.status === "underspecified") return fail(ExitCode.UNDERSPECIFIED, json, text);
@@ -1115,7 +1151,7 @@ var diagnoseCommand = {
 };
 
 // src/commands/explain-error/index.ts
-var FLAGS5 = Object.freeze([CONTRACT_FLAG]);
+var FLAGS5 = Object.freeze([EXPLAIN_CONTRACT_FLAG]);
 var POSITIONALS = Object.freeze([
   {
     name: "code",
@@ -1136,7 +1172,7 @@ var explainErrorCommand = {
       return errorOutcome("usage_error", "no error code was given", ["usage: everfur explain-error <code>"]);
     }
     const offline = resolveOffline(code);
-    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version);
+    if (offline?.kind === "sdk_member") return offlineOutcome(offline, context.version, "no_registry");
     const contractFlag = flags.string("contract");
     const contractPath = findContractPath(context, contractFlag);
     let load;
@@ -1148,10 +1184,13 @@ var explainErrorCommand = {
         ...context.contractCache === void 0 ? {} : { cache: context.contractCache }
       });
       if (fetched.kind === "unavailable") {
-        if (offline !== null) return offlineOutcome(offline, context.version);
-        const suggestions = offlineSuggestions(code);
-        return contractUnavailableOutcome(fetched, [
-          ...suggestions.length > 0 ? [`did you mean: ${suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no code similar to "${code}" exists in the SDK taxonomy or the SDK contract table this CLI carries`]
+        const resolved = resolveWithoutRegistry(code);
+        if (resolved.kind !== "unknown") return offlineOutcome(resolved, context.version, "no_registry");
+        return errorOutcome("unknown_error_code", `"${code}" is not a code this CLI knows`, [
+          ...resolved.suggestions.length > 0 ? [`did you mean: ${resolved.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : [`no similar code exists in the ${knownCodes(null).length} codes this CLI carries`],
+          "searched: the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, this CLI's error codes and the SDK's sub-enums",
+          `the live error registry was not read (${fetched.message}); it can list a code these tables predate:`,
+          ...fetched.details.filter((detail) => detail.startsWith("export "))
         ]);
       }
       load = loadErrorRegistryFromContract(fetched.contract);
@@ -1168,11 +1207,11 @@ var explainErrorCommand = {
     const entry = load.registry.lookup(code);
     if (entry === null) {
       const fallback = resolveAfterRegistryMiss(code, load.registry);
-      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version);
+      if (fallback.kind !== "unknown") return offlineOutcome(fallback, context.version, "registry_miss");
       return errorOutcome("unknown_error_code", `"${code}" is not in the error registry`, [
         ...fallback.suggestions.length > 0 ? [`did you mean: ${fallback.suggestions.join(", ")}`, "codes are case sensitive; a client branches on the literal"] : ["no similar code exists in the registry"],
         `the registry loaded from ${load.path} lists ${load.registry.codes.length} codes`,
-        `neither the SDK taxonomy nor the SDK contract table this CLI carries knows it either (${knownCodes(load.registry).length} codes searched in all)`
+        `no other table this CLI carries knows it either: the SDK taxonomy, the SDK contract table, the MCP tools' codes, the diagnostics reason codes, this CLI's error codes and the SDK's sub-enums (${knownCodes(load.registry).length} codes searched in all)`
       ]);
     }
     const input = {
@@ -1181,11 +1220,13 @@ var explainErrorCommand = {
       digest: load.digest,
       cliVersion: context.version
     };
-    return succeed(buildExplanationDocument(input), renderExplanation(input));
+    const document = { ...buildExplanationDocument(input), ...registryAlsoIn(code) };
+    return succeed(document, [renderExplanation(input), ...alsoInLines(document)].join("\n"));
   }
 };
-function offlineOutcome(resolution, cliVersion) {
-  return resolution.kind === "sdk_member" ? succeed(buildSdkExplanationDocument(resolution.code, cliVersion), renderSdkExplanation(resolution.code)) : succeed(buildContractTableExplanationDocument(resolution.row, cliVersion), renderContractTableExplanation(resolution.row));
+function offlineOutcome(resolution, cliVersion, context) {
+  const document = offlineDocument(resolution, cliVersion, context);
+  return succeed(document, renderOffline(resolution, document, context));
 }
 function contractOutcome2(outcome) {
   switch (outcome.kind) {
@@ -1233,7 +1274,11 @@ var FLAGS6 = Object.freeze([
 ]);
 var sandboxCreateCommand = {
   path: ["sandbox", "create"],
-  summary: "Provision a partner secret key and return a claim URL. Never prints the secret.",
+  /**
+   * What the command does TODAY (ROADMAP.md), not the designed claim flow: the live route returns the secret inline and
+   * no claim URL, so the key is revoked unread and the command exits 8 (SECRET_UNCLAIMABLE).
+   */
+  summary: "Everfur-internal. Mints a partner secret key and, because no claim flow exists to hand it over safely, revokes it again and exits 8. Never prints the secret.",
   usage: "sandbox create --client <client-id> [--label <text>] [--base-url <url>] [--json]",
   flags: FLAGS6,
   /** The one credential this command resolves. It never reads a partner key of either kind. */
@@ -1357,20 +1402,14 @@ function parseArgv(argv) {
   const path = [];
   const flags = /* @__PURE__ */ new Map();
   const errors = [];
-  let sawFlag = false;
   for (let index = 0; index < argv.length; index += 1) {
     const token = argv[index];
     if (token === void 0) continue;
     if (token === "--") break;
     if (!isFlagToken(token)) {
-      if (sawFlag) {
-        errors.push(`unexpected argument "${token}" after flags began`);
-      } else {
-        path.push(token);
-      }
+      path.push(token);
       continue;
     }
-    sawFlag = true;
     const equalsAt = token.indexOf("=");
     const rawName = equalsAt === -1 ? token : token.slice(0, equalsAt);
     const inlineValue = equalsAt === -1 ? null : token.slice(equalsAt + 1);
@@ -1477,7 +1516,7 @@ function renderRootHelp(commands, version) {
   lines.push("", "Global flags");
   for (const spec of GLOBAL_FLAGS) lines.push(renderFlag(spec));
   lines.push("    --version".padEnd(FLAG_COLUMN) + "Print the CLI version.");
-  lines.push(...environmentBlock(CREDENTIAL_SPECS));
+  lines.push(...environmentBlock(CREDENTIAL_SPECS, "all"));
   lines.push(
     "",
     "Not in this release",
@@ -1486,9 +1525,10 @@ function renderRootHelp(commands, version) {
   );
   return lines.join("\n");
 }
-function environmentBlock(specs) {
+function environmentBlock(specs, baseUrlFlag) {
   const lines = ["", "Environment"];
-  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + "API base URL. Overridden by --base-url.");
+  const override = baseUrlFlag === "all" ? " Overridden by --base-url on the commands that take it." : baseUrlFlag ? " Overridden by --base-url." : "";
+  lines.push(`    ${BASE_URL_ENV_VAR}`.padEnd(FLAG_COLUMN) + `API base URL.${override}`);
   for (const spec of specs) {
     lines.push(`    ${spec.envVar}`.padEnd(FLAG_COLUMN) + spec.summary);
   }
@@ -1521,7 +1561,9 @@ function renderCommandHelp(command) {
   lines.push("", "Global flags");
   for (const spec of GLOBAL_FLAGS) lines.push(renderFlag(spec));
   const credentials = command.credentials ?? [];
-  if (credentials.length > 0) lines.push(...environmentBlock(credentials));
+  if (credentials.length > 0) {
+    lines.push(...environmentBlock(credentials, command.flags.some((spec) => spec.name === "base-url")));
+  }
   return lines.join("\n");
 }
 
@@ -1561,8 +1603,10 @@ async function runCli(options) {
   const specs = match.command.positionals ?? [];
   if (positionals.length > specs.length) {
     const surplus = positionals[specs.length] ?? "";
+    const flagErrors = bindFlags(match.command.flags, parsed);
     return formatOutcome(
       errorOutcome("usage_error", `unexpected argument "${surplus}" after "${commandName(match.command)}"`, [
+        ...flagErrors.ok ? [] : flagErrors.errors,
         `usage: everfur ${match.command.usage}`
       ]),
       format

package/dist/{chunk-SJUEHHU6.js → chunk-TZVIWABT.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { hostnameOf, listen, close, writeJson, serveStatelessMcp } from './chunk-FC23PLWG.js';
-import { createHostedTokenVerifier, tokenBucketOf, isAccessTokenShaped, buildServer, MCP_SCOPE, tenantContextOf, sendTestUserRef, hostedVerifyUserRef, REVOKED_AUTHORIZATION_REMEDY, SYNTHETIC_USER_REF_PREFIX } from './chunk-XMIERMOW.js';
-import { BASE_URL_ENV_VAR, resolveEndpoint, fetchTransport, systemClock, createApiClient, withPrefix, ephemeralCredential, validateContractText, isJsonObject, describeFailure } from './chunk-KQICUK54.js';
+import { hostnameOf, listen, close, writeJson, serveStatelessMcp } from './chunk-KAHIDPBX.js';
+import { createHostedTokenVerifier, tokenBucketOf, isAccessTokenShaped, buildServer, MCP_SCOPE, tenantContextOf, sendTestUserRef, hostedVerifyUserRef, REVOKED_AUTHORIZATION_REMEDY, SYNTHETIC_USER_REF_PREFIX } from './chunk-IZGEY7H6.js';
+import { BASE_URL_ENV_VAR, resolveEndpoint, fetchTransport, systemClock, createApiClient, withPrefix, ephemeralCredential, validateContractText, isJsonObject, describeFailure } from './chunk-CGWSEOW2.js';
 import { createServer } from 'http';
 import { InvalidTokenError, TooManyRequestsError, TemporarilyUnavailableError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import { isIP } from 'net';
@@ -12,8 +12,9 @@ var PORT_ENV_VAR = "EVERFUR_MCP_HTTP_PORT";
 var LEGACY_PORT_ENV_VAR = "MCP_PORT";
 var ALLOWED_HOSTS_ENV_VAR = "MCP_ALLOWED_HOSTS";
 var ALLOWED_ORIGINS_ENV_VAR = "MCP_ALLOWED_ORIGINS";
-var DEFAULT_ALLOWED_ORIGINS = Object.freeze(["https://claude.ai", "https://claude.com"]);
+var DEFAULT_ALLOWED_ORIGINS = Object.freeze(["https://claude.ai", "https://claude.com", "https://chatgpt.com"]);
 var TRUSTED_PROXY_HOPS_ENV_VAR = "MCP_TRUSTED_PROXY_HOPS";
+var OPENAI_APPS_CHALLENGE_TOKEN_ENV_VAR = "OPENAI_APPS_CHALLENGE_TOKEN";
 var MAX_TRUSTED_PROXY_HOPS = 8;
 var DEFAULT_HOSTED_PORT = 3100;
 var DEFAULT_MCP_PATH = "/mcp";
@@ -106,6 +107,14 @@ function parseAllowedOrigins(raw) {
     return origin;
   });
 }
+function parseOpenAiAppsChallengeToken(raw) {
+  const value = (raw ?? "").trim();
+  if (value.length === 0) return null;
+  if (!/^[\x21-\x7e]+$/.test(value)) {
+    throw new Error(`${OPENAI_APPS_CHALLENGE_TOKEN_ENV_VAR} must be one token of printable ASCII, with no space or line break inside it.`);
+  }
+  return value;
+}
 function loadHostedMcpConfig(env) {
   if ((env[BASE_URL_ENV_VAR] ?? "").trim().length === 0) {
     throw new Error(`${BASE_URL_ENV_VAR} is required: the Everfur API this server verifies bearers against.`);
@@ -126,7 +135,8 @@ function loadHostedMcpConfig(env) {
     port: parsePort(env),
     allowedHosts: /* @__PURE__ */ new Set([publicHostname, ...parseAllowedHosts(env[ALLOWED_HOSTS_ENV_VAR])]),
     trustedProxyHops: parseTrustedProxyHops(env[TRUSTED_PROXY_HOPS_ENV_VAR]),
-    allowedOrigins: /* @__PURE__ */ new Set([...DEFAULT_ALLOWED_ORIGINS, ...parseAllowedOrigins(env[ALLOWED_ORIGINS_ENV_VAR])])
+    allowedOrigins: /* @__PURE__ */ new Set([...DEFAULT_ALLOWED_ORIGINS, ...parseAllowedOrigins(env[ALLOWED_ORIGINS_ENV_VAR])]),
+    openaiAppsChallengeToken: parseOpenAiAppsChallengeToken(env[OPENAI_APPS_CHALLENGE_TOKEN_ENV_VAR])
   });
 }
 function resourceMetadataUrl(config) {
@@ -265,15 +275,35 @@ The integration tools:
 - everfur_plan_integration produces an integration plan, or a refusal that names each missing fact (identity mode,
   capabilities, backend language, environment) rather than a plan built on a guess. An integration built on a guessed
   identity mode is wrong in a way that only shows up in production. Omitted, the environment is the connected tenant's.
+  A plan comes back as a small summary with a plan_id and a number of pages: the goal, the detected facts, each step's
+  id, title, one-line intent and page, and the checklist. The steps in full, with their commands and the complete file
+  bodies, come from further everfur_plan_integration calls with the same arguments plus plan_id and page, for page 1
+  to pages; page 1 also carries the detection, the warnings and the checklist in full, and the principles. (With
+  steps, step ids, instead of page, those steps come a page at a time and remaining_steps names the rest.) Each call
+  recomputes the plan from the project_details it is given, and the plan's own commands and files change the project,
+  so every page is fetched before any command runs or any file is written. The same arguments
+  and contract always produce the same plan, byte for byte. A refusal for missing facts gives each fact the developer
+  answers a fixed question and its closed list of options, so the same refusal always asks the same thing. A ready
+  plan carries a checklist: the finished integration as a fixed list of requirements, each with the check that proves
+  it. The theme is matched to the host app's own brand colours, read from its code (a Tailwind config, the CSS that
+  declares its theme, or a React Native theme file) and passed as theme_source; when none is given, the plan's
+  match-theme step names where those colours are looked for, and no colour is chosen for the host. The tenant's console
+  branding is the other side of the theme: it fills every field the theme leaves unset and wins for a field the tenant
+  locked in the partner console.
 - everfur_verify_integration exercises the real wire with a short-lived session the Everfur API mints for a synthetic
-  test user of a sandbox tenant (its entitlements report livemode false). On a live tenant the signed session step is
-  reported GATED; no session can be supplied by hand. identity_mode anonymous verifies the anonymous path instead: the
+  test user of a sandbox tenant (its entitlements report livemode false). On a live tenant with a paired sandbox the
+  session is minted on that sandbox and the call uses its publishable key; on a live tenant with no pair the signed
+  session step is reported GATED; no session can be supplied by hand. identity_mode anonymous verifies the anonymous path instead: the
   tenant's publishable key and a device session id derived for a synthetic test user, with nothing minted. It is the
-  read-only check a live tenant takes, GET requests only.
+  read-only check a live tenant takes, GET requests only. For a web page pass origin with embedding beside it: an
+  in-page page calls the API from its own origin, so the CORS checks apply to it, and with embedding in-page the
+  frame's own checks (the embed fence and the loader) are reported N/A.
 - everfur_diagnose separates the four byte-identical causes of an empty entitlement verdict.
 - everfur_explain_error looks an error code up in the contract's registry, case sensitive, and refuses a code the
   registry does not list, with near misses. Three naming families are live at once and one code is the default for
-  four different HTTP statuses, so the registry, not the shape of a code's string, says whether a retry can help.
+  four different HTTP statuses, so the registry, not the shape of a code's string, says whether a retry can help. It
+  also answers, offline, the error.code the tools on this server return (VERIFICATION_FAILED, PLAN_CHANGED and the
+  rest).
 - everfur_send_test_message sends a real message to a sandbox tenant only, and streams the real answer.
 
 The tenant tools read the connected tenant's own state and change nothing:
@@ -296,6 +326,13 @@ diagnose-integration lay out an order to call the tools in.`;
 
 // src/mcp/hosted/tenant-env.ts
 var VERIFY_SESSIONS_PATH = "/mcp/verify-sessions";
+var MINTING_TOOLS = /* @__PURE__ */ new Set(["everfur_verify_integration", "everfur_send_test_message"]);
+function hostedCallMode(context, tool, args) {
+  if (!context.tenant.livemode || context.test === null) return "connected";
+  if (!MINTING_TOOLS.has(tool)) return "connected";
+  if (tool === "everfur_verify_integration" && args["identity_mode"] === "anonymous") return "connected";
+  return "test";
+}
 function toolApiBaseUrl(context, fallback) {
   const resolved = resolveEndpoint(null, { [BASE_URL_ENV_VAR]: context.apiBaseUrl });
   return resolved.ok ? resolved.endpoint.baseUrl : fallback;
@@ -334,7 +371,9 @@ async function mintVerifySession(options) {
         sessionToken: null,
         outcome: {
           kind: "gated",
-          reason: "this tenant is live: the Everfur API mints verify sessions for sandbox tenants only",
+          // The live-tenant wording applies to an UNPAIRED live tenant only: a paired one is minted on its sandbox, and is
+          // refused only when that sandbox is no longer an active partner sandbox (EFBackend #1629).
+          reason: options.paired === true ? "this tenant is live and its paired sandbox is no longer an active sandbox: the Everfur API mints verify sessions on a sandbox tenant only" : "this tenant is live: the Everfur API mints verify sessions for sandbox tenants only",
           requestId: result.requestId
         }
       };
@@ -391,7 +430,8 @@ async function mintVerifySession(options) {
   };
 }
 function synthesizeTenantEnv(options) {
-  const publishableKey = options.context.publishableKey;
+  const test = options.mode === "test" ? options.context.test : null;
+  const publishableKey = test === null ? options.context.publishableKey : test.publishableKey;
   return Object.freeze({
     [BASE_URL_ENV_VAR]: toolApiBaseUrl(options.context, options.apiBaseUrl),
     ...publishableKey === null ? {} : { EVERFUR_PARTNER_KEY: publishableKey }
@@ -610,6 +650,7 @@ function createWellKnownMirror(options) {
 
 // src/mcp/hosted/http.ts
 var HEALTH_PATH = "/healthz";
+var OPENAI_APPS_CHALLENGE_PATH = "/.well-known/openai-apps-challenge";
 var MAX_BODY_BYTES = 1024 * 1024;
 var DRAIN_CEILING_BYTES = 16 * 1024 * 1024;
 var RETRY_AFTER_SECONDS = 5;
@@ -720,12 +761,23 @@ function createHostedMcpRequestListener(options) {
     const userRef = call.tool === "everfur_send_test_message" && typeof idempotencyKey === "string" && idempotencyKey.length > 0 ? sendTestUserRef(idempotencyKey) : hostedVerifyUserRef(typeof label === "string" ? label : void 0);
     const bearer = call.authInfo.token;
     const onUnauthorized = () => verifier.forget(bearer);
+    const mode = hostedCallMode(tenant, call.tool, call.args);
+    const paired = tenant.tenant.livemode && tenant.test !== null;
     return {
-      env: synthesizeTenantEnv({ context: tenant, apiBaseUrl: config.apiBaseUrl }),
+      env: synthesizeTenantEnv({ context: tenant, apiBaseUrl: config.apiBaseUrl, mode }),
       credentialSource: "hosted",
-      hostedMint: createHostedMint({ bearer, apiBaseUrl: config.apiBaseUrl, userRef, transport, clock, onUnauthorized }),
+      hostedMint: createHostedMint({ bearer, apiBaseUrl: config.apiBaseUrl, userRef, transport, clock, onUnauthorized, paired }),
       syntheticUserRef: userRef,
-      tenantReads: createHostedTenantReads({ bearer, apiBaseUrl: config.apiBaseUrl, transport, clock, onUnauthorized })
+      tenantReads: createHostedTenantReads({ bearer, apiBaseUrl: config.apiBaseUrl, transport, clock, onUnauthorized }),
+      tenantMode: { livemode: tenant.tenant.livemode, paired },
+      connectedTenant: {
+        slug: tenant.tenant.slug,
+        livemode: tenant.tenant.livemode,
+        pairedSandboxSlug: tenant.test === null ? null : tenant.test.slug,
+        // The prefix alone, which names the tenant mode; the key itself never leaves the context.
+        publishableKeyPrefix: ["pk_test_", "pk_live_"].find((prefix) => tenant.publishableKey?.startsWith(prefix) === true) ?? null,
+        apiBaseUrl: tenant.apiBaseUrl
+      }
     };
   };
   return async (req, res) => {
@@ -738,6 +790,21 @@ function createHostedMcpRequestListener(options) {
       writeJson(res, 200, { status: "ok" });
       return;
     }
+    const challengeToken = config.openaiAppsChallengeToken;
+    if (challengeToken !== null && url.pathname === OPENAI_APPS_CHALLENGE_PATH) {
+      const refused2 = refusalFor(req, config, ["GET", "HEAD"]);
+      if (refused2 !== null) {
+        writeJson(res, refused2.status, { error: refused2.message }, refused2.headers);
+        return;
+      }
+      res.writeHead(200, {
+        "content-type": "text/plain; charset=utf-8",
+        "content-length": String(Buffer.byteLength(challengeToken)),
+        "cache-control": "no-store"
+      });
+      res.end(req.method === "HEAD" ? void 0 : challengeToken);
+      return;
+    }
     const document = metadataPaths.get(url.pathname);
     if (document !== void 0) {
       if (req.method === "OPTIONS") {

package/dist/everfur-mcp-hosted.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { loadHostedMcpConfig, startHostedMcpServer } from './chunk-SJUEHHU6.js';
-import './chunk-FC23PLWG.js';
-import './chunk-XMIERMOW.js';
-import { CLI_VERSION } from './chunk-KQICUK54.js';
+import { loadHostedMcpConfig, startHostedMcpServer } from './chunk-TZVIWABT.js';
+import './chunk-KAHIDPBX.js';
+import './chunk-IZGEY7H6.js';
+import { CLI_VERSION } from './chunk-CGWSEOW2.js';
 
 // src/bin/everfur-mcp-hosted.ts
 async function main() {

package/dist/everfur-mcp-http.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { startRemoteMcpServer, loadRemoteMcpConfig } from './chunk-FC23PLWG.js';
-import './chunk-XMIERMOW.js';
-import { CLI_VERSION } from './chunk-KQICUK54.js';
+import { startRemoteMcpServer, loadRemoteMcpConfig } from './chunk-KAHIDPBX.js';
+import './chunk-IZGEY7H6.js';
+import { CLI_VERSION } from './chunk-CGWSEOW2.js';
 
 // src/bin/everfur-mcp-http.ts
 async function main() {

package/dist/everfur-mcp.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runStdioServer } from './chunk-XMIERMOW.js';
-import { CLI_VERSION } from './chunk-KQICUK54.js';
+import { runStdioServer } from './chunk-IZGEY7H6.js';
+import { CLI_VERSION } from './chunk-CGWSEOW2.js';
 
 // src/bin/everfur-mcp.ts
 if (process.argv.slice(2).includes("--version")) {

package/dist/everfur.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { runCli } from './chunk-4UB26D67.js';
-import { ExitCode, systemClock, fetchTransport, CLI_VERSION, nodeFileSystem, nodeContractCache } from './chunk-KQICUK54.js';
+import { runCli } from './chunk-NLB5XDNO.js';
+import { ExitCode, systemClock, fetchTransport, CLI_VERSION, nodeFileSystem, nodeContractCache } from './chunk-CGWSEOW2.js';
 
 // src/bin/everfur.ts
 async function main() {