failproofai 1.0.7-beta.2 → 1.0.8-beta.0

package/src/hooks/jev-cli.ts

@@ -10,8 +10,28 @@
  *               enabled policy set Jev is allowed to clear, and how Jev has
  *               been doing (fallbacks, latency, clears) — never the key
  *   jev test    one tiny live request: latency and the Jev version that answered
+ *   jev models  what `GET <base>/models` says this endpoint serves
  *   jev remove  delete the file; hooks go back to the regex engine unchanged
  *
+ * # `--url` is a BASE, and the model has to exist
+ *
+ * Two contract mistakes cost a customer on a LiteLLM proxy real time, and both
+ * were things this command already knew enough to say:
+ *
+ * - `--url https://…/typesafe/v1/models` was an ENDPOINT given where a BASE
+ *   belongs. It saved without complaint, `/systemone` was appended to it, and the
+ *   only signal was `http-404: Not Found` from `jev test`. Setup now refuses a URL
+ *   whose path ends in `/models`, `/chat/completions`, `/completions`,
+ *   `/embeddings` or `/systemone` and names the base it implies
+ *   (`endpointGivenAsBase`).
+ * - the model then still did not exist: `custom`'s default is `jev-1.13.0` and
+ *   that proxy serves `jev-latest` and `jev-preview`. Setup now reads
+ *   `GET <base>/models` before it writes, and refuses a model the list does not
+ *   carry, naming the ones it does. When the list cannot be read — no key yet, a
+ *   proxy that serves no list, Cloudflare, an unreachable host — setup proceeds
+ *   exactly as it did before: this is a check where one is possible, never a
+ *   dependency on a model-list endpoint existing.
+ *
  * # The provider is read off the URL
  *
  * `--url` names the endpoint, and its HOST says which provider that is
@@ -80,25 +100,42 @@ import { writeJsonAtomically } from "../../lib/atomic-write";
 import {
   DEFAULT_JEV_MODE,
   JEV_API_KEY_ENV,
+  JEV_CLOUD_PROVIDER,
   JEV_CONFIG_DEFAULT_TIMEOUT_MS,
   JEV_PROVIDER_KINDS,
+  MAX_JEV_TIMEOUT_MS,
+  endpointGivenAsBase,
   inspectJevConfig,
+  jevCloudBaseUrl,
   jevConfigPath,
+  providerForUrl,
+  providerHostConflict,
   readJevConfigFileForUpdate,
   validateApiKey,
   validateBaseUrl,
   validateJevConfig,
+  type EndpointGivenAsBase,
   type JevConfig,
+  type JevConfigInspection,
   type JevProviderKind,
 } from "./semantic/jev-config";
 import {
+  JEV_MODEL_LIST_TIMEOUT_MS,
   JEV_PROVIDER_DEFAULTS,
   JevError,
   displayEndpoint,
+  endpointAsBaseReason,
+  jevModelsUrl,
   jevRoute,
+  listDescribesSystemOne,
+  modelListHasModel,
+  modelsUrlForBase,
   readAnswers,
+  readJevModelList,
   scrubSecret,
   transportForConfig,
+  type JevModelListRead,
+  type JevModelListResult,
 } from "./semantic/jev-client";
 import {
   reviewableProblem,
@@ -107,8 +144,9 @@ import {
   type ReviewableCoverage,
 } from "./policy-reviewability";
 import { jevStats, type JevStats } from "./semantic/jev-stats";
+import { readCredentials, readJevCloudCredential, type JevCloudCredential } from "./fp-config";
 import type { JevRequest } from "./semantic/types";
-import { emptyState, nextStep, note, optsFor, rows, rule, stack, title, warning, type RenderOpts } from "./tui";
+import { TOKEN_ON_ARGV, emptyState, nextStep, note, optsFor, rows, rule, stack, title, warning, type RenderOpts } from "./tui";
 
 export interface JevCliResult {
   lines: string[];
@@ -117,6 +155,9 @@ export interface JevCliResult {
   json?: string;
 }
 
+/** `GET <base>/models`, as `setup` and `models` reach it. */
+export type JevModelListReader = (modelsUrl: string, apiKey: string | null) => Promise<JevModelListResult>;
+
 export interface JevCliDeps {
   /** Everything piped on stdin (for `--key-stdin` off a terminal). */
   readStdin?: () => Promise<string>;
@@ -125,9 +166,19 @@ export interface JevCliDeps {
   stdinIsTTY?: boolean;
   /** Budget for `jev test`'s single request. */
   testTimeoutMs?: number;
+  /**
+   * How `<base>/models` is read. The default reaches the network, which `setup`
+   * did not used to do at all — so it is injectable, and a unit test that is not
+   * about the list injects a reader that reads nothing rather than calling out to
+   * a provider from a test run.
+   */
+  readModelList?: JevModelListReader;
   render?: RenderOpts;
 }
 
+/** The real reader, on its own budget: see `JEV_MODEL_LIST_TIMEOUT_MS`. */
+const liveModelListReader: JevModelListReader = (url, apiKey) => readJevModelList(url, apiKey, AbortSignal.timeout(JEV_MODEL_LIST_TIMEOUT_MS));
+
 const ok = (lines: string[], json?: string): JevCliResult => ({ lines, exitCode: 0, ...(json !== undefined ? { json } : {}) });
 const fail = (lines: string[], json?: string): JevCliResult => ({ lines, exitCode: 1, ...(json !== undefined ? { json } : {}) });
 
@@ -135,8 +186,10 @@ export const JEV_USAGE = [
   "Usage:",
   "  failproofai jev --url <url> [--key-stdin | --token <token>] [options]",
   "  failproofai jev setup --provider <kind> [--key-stdin | --key-from-env] [options]",
+  "  failproofai jev setup --provider failproofai [--mode off|shadow|enforce]   (FailproofAI Cloud: no key, no URL)",
   "  failproofai jev status [--json]",
   "  failproofai jev test [--json]",
+  "  failproofai jev models [--provider <kind>] [--url <base>] [--json]",
   "  failproofai jev remove",
 ];
 
@@ -213,11 +266,84 @@ function parseFlags(argv: string[], allowed: Set<string>): Parsed | string {
 // ── Rendering helpers ────────────────────────────────────────────────────────
 
 function modeLine(mode: NonNullable<JevConfig["mode"]>): string {
+  if (mode === "off") return "off — Jev is not asked at all; the regex policies decide alone";
   return mode === "enforce"
     ? "enforce — Jev's verdicts apply: it may clear a reviewable policy's deny and add its own"
     : "shadow — Jev is asked and logged; the regex result is what is enforced";
 }
 
+/**
+ * The name a provider is SHOWN by. Only the Cloud route differs from its kind:
+ * `failproofai` is the value in the file, and "FailproofAI Cloud" is what the
+ * person connected to.
+ */
+export function providerLabel(provider: JevProviderKind): string {
+  return provider === JEV_CLOUD_PROVIDER ? "FailproofAI Cloud" : provider;
+}
+
+/**
+ * Where requests go, as `jev status` shows it. The Cloud route shows its HOST
+ * only: the path under it is the Cloud's own routing, the same on every
+ * deployment, and the host is the one fact that says which Cloud this machine
+ * is talking to.
+ */
+function shownEndpoint(provider: JevProviderKind, endpoint: string): string {
+  if (provider !== JEV_CLOUD_PROVIDER) return displayEndpoint(endpoint);
+  try {
+    return new URL(endpoint).host;
+  } catch {
+    return "(invalid URL)";
+  }
+}
+
+/** What `jev status` says about where the key comes from. */
+const CLOUD_KEY_SOURCE = "FailproofAI Cloud connection";
+
+/** Whether this machine holds a usable Jev credential, read owner-only. Never the key. */
+function cloudCredentialPresent(): boolean {
+  return cloudConnection().keyCarriesJev;
+}
+
+/**
+ * Whether a refused or missing jev.json is fixed from the Cloud connection: it
+ * names the Cloud, or it names no provider (absent, not JSON) on a machine whose
+ * key carries Jev — which is what `config --token` suggests for the same file.
+ */
+function cloudRoute(raw: Record<string, unknown> | null | undefined): boolean {
+  return raw?.provider === JEV_CLOUD_PROVIDER || (raw?.provider === undefined && cloudCredentialPresent());
+}
+
+/**
+ * The two facts `status --json` reports about the FailproofAI Cloud connection,
+ * read owner-only: whether this machine is connected at all, and whether the
+ * key it connected with carries Jev. Never the key.
+ */
+function cloudConnection(): { cloudConnected: boolean; keyCarriesJev: boolean } {
+  try {
+    const read = readJevCloudCredential();
+    if (read.status === "ok") return { cloudConnected: true, keyCarriesJev: true };
+    if (read.status === "absent") return { cloudConnected: read.connected, keyCarriesJev: false };
+    // Refused (a loose or unreadable credentials.json): no key is usable, but a
+    // connection on record is still a connection — as the dashboard reads it.
+    const creds = readCredentials();
+    return { cloudConnected: Boolean(creds.cloud?.url ?? creds.ingest?.url), keyCarriesJev: false };
+  } catch {
+    return { cloudConnected: false, keyCarriesJev: false };
+  }
+}
+
+/** The one line `status` titles a connected machine whose key has no Jev with. */
+const KEY_LACKS_JEV_TITLE = "off — no Jev key is stored for this machine's FailproofAI Cloud connection";
+
+/** The `key` row for a Cloud file, saying which of the three states the connection is in. */
+function cloudKeyRow(): string {
+  const c = cloudConnection();
+  if (c.keyCarriesJev) return CLOUD_KEY_SOURCE;
+  return c.cloudConnected
+    ? `${CLOUD_KEY_SOURCE} — connected, no Jev key stored for it`
+    : `${CLOUD_KEY_SOURCE} — this machine is not connected`;
+}
+
 /** `0600`, or null when unknown. */
 function octal(mode: number | null): string | null {
   return mode === null ? null : mode.toString(8).padStart(4, "0");
@@ -238,10 +364,68 @@ function scrubbed(e: { code: string; message: string }, key: string): { code: st
   return { code: e.code, message: scrubSecret(e.message, key) };
 }
 
+/**
+ * What the person should do about a failed FailproofAI Cloud request, by cause,
+ * or null where the generic advice already fits. The remedies differ from a
+ * BYOK provider's because the key and the budget are the Cloud connection's and
+ * the org's, not anything `jev setup` holds.
+ */
+function cloudRemedy(code: string, message = ""): string | null {
+  if (code === "http-401" || code === "http-403") {
+    return "FailproofAI Cloud refused this machine's key: it was revoked, or it does not carry jev:evaluate. Reconnect with a key that does (the \"machine\" preset on the Keys page): failproofai config --token <key>";
+  }
+  if (code === "out-of-credits") {
+    return "Your FailproofAI Cloud org has used its plan allowance (HTTP 402). Until it resets or the plan changes, hooks fall back to regex.";
+  }
+  if (code === "http-429") {
+    // Two limits answer 429 (contract decision 18): the per-minute ones, and
+    // the org's daily Jev cap, whose body says `daily_limit_reached` and whose
+    // Retry-After runs to the next UTC midnight. Only the words tell them
+    // apart, and "right now … at most 60 s" is wrong for the second: the
+    // machine still asks again after at most 60 s, and keeps being refused.
+    if (/\bdaily_limit_reached\b/.test(message)) {
+      return "Daily Jev limit for this org reached; resets at 00:00 UTC. Until then hooks fall back to regex; the machine asks FailproofAI Cloud again at most once a minute (Retry-After, capped at 60 s).";
+    }
+    return "FailproofAI Cloud is rate-limiting Jev for this org right now. Hooks fall back to regex, and send it nothing more until the wait it asked for (Retry-After, at most 60 s) is over.";
+  }
+  if (code === "http-404") return "This FailproofAI Cloud does not serve Jev (its server predates the Jev route). Hooks fall back to regex until it does.";
+  if (code === "http-503") {
+    return (
+      "This FailproofAI Cloud cannot serve Jev for your org: its deployment has no model gateway, the org is not " +
+      "provisioned yet, or the gateway is down. Ask your FailproofAI Cloud admin. Hooks fall back to regex and ask " +
+      "again at most once a minute."
+    );
+  }
+  // `request_rejected`: TypeSafe refused this request itself, typically dense
+  // text over Jev's token budget. The same call gets the same answer.
+  if (code === "http-422") return "Jev refused this call's request, usually because it held dense text (base64, hex, minified code) over Jev's token budget. That call falls back to regex every time; this is not an outage.";
+  if (code === "model-mismatch") return "FailproofAI Cloud answered with a model outside the Jev 1.13 family, so hooks would fall back to regex. This is the server's to fix.";
+  // The generic advice for these names `--base-url`, which this route refuses:
+  // its endpoint is the Cloud this machine connected to, changed only by
+  // reconnecting.
+  if (/^http-3(?:\d\d|xx)$/.test(code)) {
+    return "FailproofAI Cloud answered with a redirect, and Jev requests never follow one. The URL this machine connected to is probably not the one that serves the API (a sign-in page, or an old address). Reconnect with the right one: failproofai config --token <key> --url <url>";
+  }
+  if (code === "network") {
+    return "FailproofAI Cloud could not be reached. Check your network; if the Cloud's address has changed, reconnect: failproofai config --token <key> --url <url>";
+  }
+  if (code === "config") return "The config is not usable. Rebuild it from this machine's FailproofAI Cloud connection: failproofai jev setup --provider failproofai";
+  return null;
+}
+
 /** What the person should do about a failed request, by cause. */
-function remedy(code: string): string {
+function remedy(code: string, provider?: JevProviderKind, message?: string): string {
+  if (provider === JEV_CLOUD_PROVIDER) {
+    const cloud = cloudRemedy(code, message);
+    if (cloud) return cloud;
+  }
   if (code === "http-401" || code === "http-403") return "The provider refused the key. Re-run `failproofai jev setup` with the right one.";
   if (code === "out-of-credits") return "The account is out of credits (HTTP 402). Top it up with the provider; until then hooks fall back to regex.";
+  // The message from `httpFailureMessage` has already said what a 404 there
+  // means; this is the part that is an instruction rather than a diagnosis.
+  if (code === "http-404") {
+    return "Set the base URL to the provider's version root, without the endpoint path: `failproofai jev setup --base-url <base>`. `failproofai jev models` says what a base serves.";
+  }
   if (code === "http-429") return "The provider rate-limited this key. Hooks fall back to regex whenever that happens.";
   if (code.startsWith("http-5")) return "The provider had a server error. Hooks fall back to regex whenever that happens; try again shortly.";
   if (code === "timeout") return "No answer in time. Check the endpoint and your network.";
@@ -323,28 +507,6 @@ function movedHost(provider: JevProviderKind, before: unknown, after: unknown):
   return { from, to };
 }
 
-/**
- * The provider each known host IS, so `failproofai jev --url <url>` needs no
- * `--provider`. Exact hosts only: a neighbouring name (`eu.api.typesafe.ai`, a
- * corporate proxy) is `custom`, which reaches the same TypeSafe-compatible API
- * at the URL given, and `--provider` is there to say otherwise.
- */
-const PROVIDER_BY_HOST: Readonly<Record<string, JevProviderKind>> = {
-  "api.typesafe.ai": "typesafe",
-  "openrouter.ai": "openrouter",
-  "ai-gateway.vercel.sh": "vercel",
-  "api.cloudflare.com": "cloudflare",
-};
-
-/** The provider a validated URL names, or `custom` for a host that is nobody's. */
-function providerForUrl(url: string): JevProviderKind {
-  try {
-    return PROVIDER_BY_HOST[new URL(url).hostname.toLowerCase()] ?? "custom";
-  } catch {
-    return "custom";
-  }
-}
-
 /**
  * The account id a Cloudflare URL already carries, or null.
  *
@@ -360,7 +522,7 @@ function providerForUrl(url: string): JevProviderKind {
 export function accountIdFromUrl(url: string): string | null {
   try {
     const parsed = new URL(url);
-    if (PROVIDER_BY_HOST[parsed.hostname.toLowerCase()] !== "cloudflare") return null;
+    if (providerForUrl(url) !== "cloudflare") return null;
     const m = /\/accounts\/([0-9a-f]{32})(?:\/|$)/i.exec(parsed.pathname);
     return m ? m[1].toLowerCase() : null;
   } catch {
@@ -402,6 +564,70 @@ function offProviderBase(cfg: JevConfig, endpoint: string): { endpoint: string;
   }
 }
 
+/**
+ * The refusal for a URL that is an endpoint where a base belongs.
+ *
+ * Both URLs go through `displayEndpoint`, which replaces a query string with
+ * `?…`: a proxy base may legitimately carry `?api-version=` — or a token — and a
+ * refusal is not a reason to print one. That does make the suggested command a
+ * shape rather than something to paste, which is the right trade: the person has
+ * their own URL, and the point of the line is which segment to drop.
+ */
+function endpointAsBaseRefusal(flag: string, given: string, found: EndpointGivenAsBase): string[] {
+  return [
+    `Not saved: ${flag} names an endpoint, not an API base — its path ends in ${found.suffix}.`,
+    endpointAsBaseReason(given),
+    "Give the base it sits under:",
+    `  failproofai jev ${flag} ${displayEndpoint(found.base)}`,
+    "",
+    "Nothing was written.",
+  ];
+}
+
+/** At most this many names in one refusal or one rendered list; the rest are counted. */
+const MAX_SHOWN_MODELS = 20;
+
+/** Model names for one line, bounded — the list came from a provider and may be long. */
+function shownModels(models: string[]): string {
+  if (models.length <= MAX_SHOWN_MODELS) return models.join(", ");
+  return `${models.slice(0, MAX_SHOWN_MODELS).join(", ")} … and ${models.length - MAX_SHOWN_MODELS} more`;
+}
+
+/**
+ * The list this config's endpoint serves, when it both could be read AND is
+ * authoritative about `<base>/systemone` AND does not carry the configured model
+ * — i.e. the one case that is worth refusing. Null in every other case, so a
+ * caller's "carry on unchanged" path is the default rather than the exception.
+ *
+ * `apiKey` is passed separately because a `--key-from-env` config in a shell with
+ * no variable set holds a stand-in, which must not be sent anywhere; the public
+ * lists (Vercel's, OpenRouter's) answer without a key anyway.
+ */
+async function modelAbsentFromList(
+  cfg: JevConfig,
+  model: string,
+  apiKey: string | null,
+  read: JevModelListReader,
+): Promise<{ list: JevModelListRead; url: string } | null> {
+  let url: string | null;
+  try {
+    url = jevModelsUrl(cfg);
+  } catch {
+    return null;
+  }
+  if (url === null) return null;
+  let list: JevModelListResult;
+  try {
+    list = await read(url, apiKey);
+  } catch {
+    // A reader that throws is a reader that read nothing, which is the case this
+    // whole check is required to survive.
+    return null;
+  }
+  if (!list.ok || !listDescribesSystemOne(list) || modelListHasModel(list, model)) return null;
+  return { list, url };
+}
+
 async function readAllStdin(): Promise<string> {
   const chunks: Buffer[] = [];
   for await (const chunk of process.stdin) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
@@ -413,7 +639,20 @@ async function maskedPrompt(): Promise<string | null> {
   return promptText({ message: "Jev API key", mask: true, validate: (v) => validateApiKey(v) });
 }
 
+/** What a run that put the key in argv ends with, saved or refused: the key is in history either way. */
+const TOKEN_HISTORY_WARNING = [
+  TOKEN_ON_ARGV,
+  "Prefer piping the key in — `failproofai jev --url <url> --key-stdin < key-file` — and rotate this one if it matters.",
+];
+
 async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise<JevCliResult> {
+  const r = await setupRun(argv, deps, opts);
+  // A save says it in its own place; every refusal says it here.
+  const tokenGiven = argv.some((a, i) => a.startsWith("--token=") || (a === "--token" && i + 1 < argv.length));
+  return r.exitCode === 0 || !tokenGiven ? r : { ...r, lines: [...r.lines, "", ...TOKEN_HISTORY_WARNING] };
+}
+
+async function setupRun(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise<JevCliResult> {
   const parsed = parseFlags(argv, new Set([...VALUE_FLAGS, "--key-stdin", "--key-from-env"]));
   if (typeof parsed === "string") return fail([parsed, "", ...JEV_USAGE]);
   if (parsed.positionals.length > 0) return fail([STRAY_ARGUMENT, "", ...JEV_USAGE]);
@@ -450,6 +689,22 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
     ]);
   }
 
+  // FailproofAI Cloud has a setup of its own: its endpoint and key come from the
+  // machine's connection, so none of the flags below that choose them apply.
+  // Reached by naming it, or by re-running setup (a mode switch, say) over a
+  // Cloud file without naming another provider or a URL — never by a URL: a
+  // `--url` is a BYOK endpoint whatever host it names (`PROVIDER_BY_HOST`
+  // deliberately has no Cloud entry).
+  if (
+    namedProvider === JEV_CLOUD_PROVIDER ||
+    (namedProvider === undefined &&
+      !values.has("--url") &&
+      !values.has("--base-url") &&
+      readJevConfigFileForUpdate()?.raw.provider === JEV_CLOUD_PROVIDER)
+  ) {
+    return cloudSetup(values, bools, opts);
+  }
+
   // `--url` is `--base-url` that also picks the provider. It is validated here,
   // by the loader's own `validateBaseUrl`, so a URL is refused in the same
   // words whichever way it arrived — and so the host below is a parsed host,
@@ -467,24 +722,15 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
     // An explicit provider wins — except where it disagrees with the host about
     // which gateway this is, which is a disagreement about where the key goes.
     // `custom` is not a disagreement: it is the "treat this URL as itself" ask.
-    if (explicit !== null && explicit !== "custom" && urlProvider.kind !== "custom" && explicit !== urlProvider.kind) {
+    // The rule is `providerHostConflict`'s, shared with `--base-url` below and
+    // the dashboard's save; only the advice here is about `--url`.
+    const conflict = explicit === null ? null : providerHostConflict(explicit, normalized);
+    if (conflict !== null) {
       return fail([
-        `--provider ${explicit} and --url disagree: ${urlProvider.host} is ${urlProvider.kind}'s endpoint, not ${explicit}'s.`,
-        "Drop --provider to take the provider from the URL, or give the URL that provider's own endpoint.",
-        "",
-        "Nothing was written.",
-      ]);
-    }
-    // The one host where "treat this URL as itself" cannot be honoured. A
-    // `custom` route POSTs the TypeSafe-native body to `<url>/systemone` and
-    // reads a bare answer back; Workers AI answers at `/accounts/<id>/ai/run`
-    // and wraps its answer in `result`, which is why it has a provider of its
-    // own. Saved as `custom` it would ask for the `--account-id` it then had
-    // nowhere to put, and every call would fall back to regex.
-    if (explicit === "custom" && urlProvider.kind === "cloudflare") {
-      return fail([
-        `Not saved: ${urlProvider.host} is Cloudflare Workers AI, which provider custom cannot reach — its endpoint is per-account and its answers are wrapped, and a custom endpoint is asked in TypeSafe's own shape at <url>/systemone.`,
-        "Use the provider that speaks it: --provider cloudflare --account-id <32 hex characters> — or drop --provider, since the URL already says cloudflare.",
+        explicit === "custom" ? `Not saved: ${conflict}.` : `--provider ${explicit} and --url disagree: ${conflict}.`,
+        explicit === "custom"
+          ? "Use the provider that speaks it: --provider cloudflare --account-id <32 hex characters> — or drop --provider, since the URL already says cloudflare."
+          : "Drop --provider to take the provider from the URL, or give the URL that provider's own endpoint.",
         "",
         "Nothing was written.",
       ]);
@@ -526,6 +772,21 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
     values.delete("--url");
   }
 
+  // An endpoint given where a base belongs, whichever flag carried it — `--url`
+  // has already become `--base-url` above, so the flag NAMED here is the one the
+  // person typed. Before the key is asked for, and before anything is written:
+  // the fix is one segment, and nothing should be stored or prompted for first.
+  const baseArg = values.get("--base-url");
+  if (baseArg !== undefined && baseArg !== "default") {
+    const checkedBase = validateBaseUrl(baseArg);
+    // An unusable URL is refused by validation below, in its own words; this
+    // check only has something to say about one that parses.
+    if (checkedBase.ok) {
+      const asEndpoint = endpointGivenAsBase(checkedBase.value);
+      if (asEndpoint) return fail(endpointAsBaseRefusal(urlArg !== undefined ? "--url" : "--base-url", checkedBase.value, asEndpoint));
+    }
+  }
+
   const existingFile = readJevConfigFileForUpdate();
   const existing = existingFile?.raw ?? null;
   const providerArg = values.get("--provider");
@@ -542,6 +803,22 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
     return fail(["Unknown provider (not repeated here, in case it is a key).", `Providers: ${JEV_PROVIDER_KINDS.join(", ")}`]);
   }
   const kind = provider as JevProviderKind;
+  // The same rule for a `--base-url` typed as such (a `--url` was checked above,
+  // with advice about `--url`), so the flag and the dashboard cannot save a
+  // pair `--url` refuses.
+  const typedBase = urlArg === undefined ? values.get("--base-url") : undefined;
+  const checkedTyped = typedBase === undefined || typedBase === "default" ? null : validateBaseUrl(typedBase);
+  const hostConflict = checkedTyped?.ok ? providerHostConflict(kind, checkedTyped.value) : null;
+  if (checkedTyped?.ok && hostConflict !== null) {
+    return fail([
+      `Not saved: ${hostConflict}.`,
+      kind === "custom"
+        ? "Use the provider that speaks it: --provider cloudflare --account-id <32 hex characters>."
+        : `Give ${kind}'s own endpoint, or the provider this URL belongs to: --provider ${providerForUrl(checkedTyped.value)}.`,
+      "",
+      "Nothing was written.",
+    ]);
+  }
   const sameProvider = existing !== null && existing.provider === provider;
 
   // Same provider: update in place, keeping the key and every field not named
@@ -718,6 +995,42 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
   if (!checked.ok) return fail([`Not saved: ${checked.problem}.`, "", "Nothing was written."]);
   const cfg = checked.value;
 
+  // The model, against what the endpoint says it serves. This is the second half
+  // of the LiteLLM-proxy failure: the URL was fixed and the default model still
+  // did not exist there, which nothing said until `jev test` returned a 404 and
+  // the person curled the endpoint by hand.
+  //
+  // Never a hard requirement: a list that cannot be read (no key yet, a proxy
+  // that serves none, Cloudflare, an unreachable host, a shape nobody knows) and
+  // a list that is not authoritative about `/systemone` both fall through to the
+  // write, so this can only ever turn a silent misconfiguration into a refusal —
+  // it can never turn a working setup into a failing one.
+  const routeForCheck = ((): ReturnType<typeof jevRoute> | null => {
+    try {
+      return jevRoute(cfg);
+    } catch {
+      return null;
+    }
+  })();
+  if (routeForCheck !== null) {
+    // The stand-in is not a key and must not be sent; the public lists answer
+    // without one, so the read is still worth making.
+    const listKey = keyFromEnv && !envKey ? null : cfg.apiKey;
+    const absent = await modelAbsentFromList(cfg, routeForCheck.model, listKey, deps.readModelList ?? liveModelListReader);
+    if (absent) {
+      return fail([
+        `Not saved: ${displayEndpoint(absent.url)} does not list ${routeForCheck.model}, so every request would fail there.`,
+        `  it serves: ${shownModels(absent.list.models)}`,
+        routeForCheck.modelIsDefault
+          ? `${routeForCheck.model} is this build's default for provider ${provider}, and this endpoint names Jev differently — so --model is not optional here. Add it to the command you just ran:`
+          : "Pick one of the names above:",
+        `  --model ${absent.list.models[0]}`,
+        "",
+        "Nothing was written.",
+      ]);
+    }
+  }
+
   const path = jevConfigPath();
   try {
     writeJsonAtomically(path, next, { mode: 0o600, dirMode: 0o700 });
@@ -793,17 +1106,223 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
       // command line it came on is not — it is in this shell's history file and
       // was readable from /proc by anything running as this user while the
       // process lived.
-      tokenOnCommandLine
-        ? warning(
-            [
-              "--token was on the command line: your shell history has it, and while this command ran any process of yours could read it from the process list.",
-              "Prefer piping the key in — `failproofai jev --url <url> --key-stdin < key-file` — and rotate this one if it matters.",
-            ],
-            opts,
-          )
-        : null,
+      tokenOnCommandLine ? warning(TOKEN_HISTORY_WARNING, opts) : null,
       note("Hooks read this file on every tool call — no restart. Without it they run the regex policies exactly as before.", opts),
-      nextStep("failproofai jev test", "Check it with one live request:", opts),
+      // Switched off, `jev test` only answers "not run — switched off": a next
+      // step that leads nowhere is worse than none.
+      (cfg.mode ?? DEFAULT_JEV_MODE) === "off" ? null : nextStep("failproofai jev test", "Check it with one live request:", opts),
+    ),
+  );
+}
+
+// ── setup: FailproofAI Cloud ─────────────────────────────────────────────────
+
+/** How `inspectJevConfig` opens a refusal that is about credentials.json. */
+const CLOUD_CREDENTIAL_REFUSED = "the FailproofAI Cloud credential was refused";
+
+/**
+ * The next step for a refused config: one ladder, so `status` and `test` never
+ * disagree about the same inspection.
+ */
+function refusedNextStep(inspection: Extract<JevConfigInspection, { status: "refused" }>, cloudFile: boolean): { cmd: string; lead: string } {
+  // The Cloud route's key file is credentials.json, and a refusal can be about
+  // THAT file: the key it holds was put there by `config --token`, not by
+  // anything `jev setup` could re-ask for.
+  if (cloudFile && inspection.problem.startsWith(CLOUD_CREDENTIAL_REFUSED)) {
+    if (inspection.reason !== "too-open") {
+      return { cmd: "failproofai config --token <key>", lead: "credentials.json could not be read. Reconnect, which rewrites it at 0600:" };
+    }
+    const m = inspection.credentialsMode ?? 0;
+    const risks = [
+      ...((m & 0o044) !== 0 ? ["other users can read it, and with it spend this machine's FailproofAI Cloud key"] : []),
+      ...((m & 0o022) !== 0 ? ["other users could change it"] : []),
+    ];
+    const risk = risks.length > 0 ? risks.join(", and ") : "other users can write where it lives, so they could put their own in its place";
+    return {
+      cmd: inspection.fix ?? "failproofai config --token <key>",
+      lead: `credentials.json holds the key Jev sends to FailproofAI Cloud, and ${risk}. Make it owner-only (or reconnect, which rewrites it at 0600):`,
+    };
+  }
+  if (inspection.reason === "too-open") {
+    // Read bits alone expose the key in it; only write bits (or a loose
+    // directory, where the file's own mode is owner-only) let others change it.
+    const m = inspection.mode ?? 0;
+    const readOnly = (m & 0o044) !== 0 && (m & 0o022) === 0;
+    return {
+      // Either the file or the directory it sits in; `fix` says which.
+      cmd: inspection.fix ?? `chmod 600 ${inspection.path}`,
+      lead: readOnly
+        ? inspection.keyless
+          ? "Make it owner-only:"
+          : "Other users can read this file, and with it any key it holds. Make it owner-only (and rotate the key if it matters):"
+        : cloudFile
+          ? "Other users could change this file, so check that endpoint is one you chose. Then make it owner-only (or rebuild it from this machine's connection: `failproofai jev setup --provider failproofai`):"
+          : "Other users could change this file, so check that endpoint is one you chose. Then make it owner-only (or re-run `failproofai jev setup`, which asks for the key again unless the endpoint is the provider's own):",
+    };
+  }
+  if (cloudFile) return { cmd: "failproofai jev setup --provider failproofai", lead: "Rewrite it from this machine's FailproofAI Cloud connection:" };
+  return { cmd: "failproofai jev setup --provider <kind> --key-stdin", lead: "Write a valid one:" };
+}
+
+/**
+ * `jev setup --provider failproofai`, and any setup run over a Cloud file.
+ *
+ * The Cloud route has nothing to choose but its mode and timeout: the endpoint
+ * is `<Cloud base>/enforcement/v1/jev` on the origin the machine connected to,
+ * the key is the connection's own (`credentials.json`, never this file) and the
+ * model is pinned by the server. So every flag that would choose one of those is
+ * refused — naming it would be asking for something this route cannot honour —
+ * and the file is rebuilt from the connection. An `apiKey` a hand-edited file
+ * carries is dropped, which is also what makes such a file valid again.
+ *
+ * A mode or timeout change on an existing Cloud file does not need the machine
+ * to be connected: it changes nothing about where a key goes. Creating one,
+ * or rebuilding its endpoint, does.
+ */
+async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts: RenderOpts): Promise<JevCliResult> {
+  const refusedFlag = (["--token", "--url", "--base-url", "--account-id", "--model"] as const).find((f) => values.has(f)) ??
+    (["--key-stdin", "--key-from-env"] as const).find((f) => bools.has(f));
+  if (refusedFlag !== undefined) {
+    const why =
+      refusedFlag === "--model"
+        ? `FailproofAI Cloud runs ${JEV_PROVIDER_DEFAULTS.failproofai.model}, pinned on the server; there is no model to choose.`
+        : refusedFlag === "--account-id"
+          ? "--account-id is Cloudflare's; FailproofAI Cloud has no use for one."
+          : refusedFlag === "--url" || refusedFlag === "--base-url"
+            ? "FailproofAI Cloud's endpoint is the one this machine connected to; to change it, reconnect: failproofai config --token <key> --url <url>"
+            : "FailproofAI Cloud's key is this machine's connection key, kept in credentials.json and never in jev.json; to change it, reconnect: failproofai config --token <key>";
+    return fail([`Not saved: ${refusedFlag} does not apply to provider failproofai. ${why}`, "", "Nothing was written."]);
+  }
+
+  const existing = readJevConfigFileForUpdate();
+  const sameProvider = existing?.raw.provider === JEV_CLOUD_PROVIDER;
+  const credential = readJevCloudCredential();
+  if (credential.status === "refused") {
+    return fail([`Not saved: ${credential.problem}.`, "", "Nothing was written."]);
+  }
+
+  const next: Record<string, unknown> = sameProvider ? { ...existing!.raw } : { provider: JEV_CLOUD_PROVIDER };
+  // Never a key in a Cloud file, and nothing only another provider reads.
+  delete next.apiKey;
+  delete next.accountId;
+  if (!sameProvider && existing?.raw.timeoutMs !== undefined) next.timeoutMs = existing.raw.timeoutMs;
+  // Shadow unless told otherwise, as `config --token` starts it: Jev on a new
+  // route is logged before it is allowed to clear anything. A mode already in a
+  // Cloud file is kept.
+  const mode = values.get("--mode") ?? (sameProvider && typeof next.mode === "string" ? next.mode : "shadow");
+  next.mode = mode;
+  if (values.has("--timeout-ms")) {
+    const rawTimeout = values.get("--timeout-ms") as string;
+    const n = Number(rawTimeout);
+    if (!/^\d+$/.test(rawTimeout) || !Number.isSafeInteger(n)) return fail(["Could not read --timeout-ms. Give a whole number of milliseconds."]);
+    next.timeoutMs = n;
+  }
+
+  let keySource: JevCloudCredential | null = null;
+  if (credential.status === "ok") {
+    keySource = credential.credential;
+    // The endpoint, from the connection: kept when it is already on the
+    // credential's origin, else rebuilt — under the policy connection's base
+    // when that is on the same origin, so a path prefix survives.
+    const onOrigin = (u: unknown) => {
+      try {
+        return typeof u === "string" && new URL(u).origin === new URL(credential.credential.url).origin;
+      } catch {
+        return false;
+      }
+    };
+    if (!onOrigin(next.baseUrl)) {
+      const policyBase = readCredentials().cloud?.url;
+      next.baseUrl = jevCloudBaseUrl(onOrigin(policyBase) ? (policyBase as string) : credential.credential.url);
+    }
+  } else if (!sameProvider || typeof next.baseUrl !== "string") {
+    return fail([
+      ...(credential.connected
+        ? [
+            // Its key may well carry jev:evaluate: an older failproofai connected
+            // without storing a Jev key, and the same key fixes that.
+            "Not saved: this machine is connected to FailproofAI Cloud, but no Jev key is stored for that connection.",
+            "Reconnect with this machine's key to re-check what it carries (an older failproofai connected without storing its Jev key; " +
+              "a key without jev:evaluate needs the \"machine\" preset on the dashboard's Keys page):",
+          ]
+        : [
+            "Not saved: this machine is not connected to FailproofAI Cloud with a key that carries jev:evaluate.",
+            "Connect it with one that does (the \"machine\" preset) — that also turns Jev on, in shadow mode, when there is no jev.json yet:",
+          ]),
+      "  failproofai config --token <key>",
+      "",
+      "Nothing was written.",
+    ]);
+  }
+
+  // The loader's own rules, with the connection's key or — for a mode switch
+  // on a machine that is not connected right now — a stand-in on the file's own
+  // origin, which is never written or sent.
+  let standInOrigin = "";
+  try {
+    standInOrigin = new URL(String(next.baseUrl)).origin;
+  } catch {
+    standInOrigin = "";
+  }
+  const checked = validateJevConfig(next, null, keySource ?? { url: standInOrigin, key: ENV_KEY_STAND_IN });
+  if (!checked.ok) return fail([`Not saved: ${checked.problem}.`, "", "Nothing was written."]);
+
+  const path = jevConfigPath();
+  try {
+    writeJsonAtomically(path, next, { mode: 0o600, dirMode: 0o700 });
+  } catch (err) {
+    return fail([`Could not write ${path}: ${(err as NodeJS.ErrnoException).code ?? "error"}.`]);
+  }
+  if (process.platform !== "win32") {
+    try {
+      const dir = dirname(path);
+      const before = statSync(dir).mode & 0o777;
+      if ((before & 0o022) !== 0) chmodSync(dir, before & ~0o022);
+    } catch {
+      // Not fatal: the loader reports a directory it will not read from.
+    }
+  }
+  let fileMode: number | null = null;
+  try {
+    fileMode = statSync(path).mode & 0o777;
+  } catch {
+    // Reported as unknown below.
+  }
+
+  const cfg = checked.value;
+  const route = jevRoute(cfg);
+  const shownMode = cfg.mode ?? DEFAULT_JEV_MODE;
+  return ok(
+    stack(
+      title("failproofai jev setup", `saved · FailproofAI Cloud · ${shownMode}`, opts),
+      rows(
+        [
+          ["provider", providerLabel(JEV_CLOUD_PROVIDER)],
+          ["endpoint", shownEndpoint(JEV_CLOUD_PROVIDER, route.endpoint)],
+          ["model", `${route.model} (pinned by FailproofAI Cloud)`],
+          ["mode", modeLine(shownMode)],
+          ["timeout", `${cfg.timeoutMs} ms`],
+          // Which of the three states the connection is in — the same row
+          // `status` shows. "Not connected" on a machine that IS connected, with
+          // a key that lacks Jev, sent its owner to reconnect with that same key.
+          ["key", keySource ? CLOUD_KEY_SOURCE : cloudKeyRow()],
+          ["config", path],
+          ["permissions", permissions(fileMode)],
+        ],
+        opts,
+      ),
+      note("Hooks read this file on every tool call — no restart. Calls are charged to your FailproofAI Cloud org's plan.", opts),
+      // With no usable key, `jev test` only answers "not run": the step that
+      // helps is the connection. Switched off, there is no step to take.
+      shownMode === "off"
+        ? null
+        : keySource
+          ? nextStep("failproofai jev test", "Check it with one live request:", opts)
+          : nextStep(
+              "failproofai config --token <key>",
+              "Jev stays off until this machine is connected with a key that carries jev:evaluate (the \"machine\" preset on the dashboard's Keys page):",
+              opts,
+            ),
     ),
   );
 }
@@ -824,15 +1343,30 @@ async function setup(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promis
  */
 function routeForRouting(routing: Omit<JevConfig, "apiKey">): ReturnType<typeof jevRoute> | null {
   try {
-    return jevRoute({ ...routing, apiKey: ENV_KEY_STAND_IN });
+    return jevRoute({ ...routing, apiKey: ENV_KEY_STAND_IN, ...displayOnlyCloudOrigin(routing) });
   } catch {
     return null;
   }
 }
 
+/**
+ * For DISPLAY only, like the stand-in key beside it: a FailproofAI Cloud route
+ * is built only against the origin of the credential it was validated with
+ * (`validateLoadedJevConfig`), and a config shown here has no credential behind
+ * it, so the file's own origin stands in. Nothing built with it is ever sent.
+ */
+function displayOnlyCloudOrigin(routing: { provider?: unknown; baseUrl?: unknown }): { credentialOrigin?: string } {
+  if (routing.provider !== JEV_CLOUD_PROVIDER || typeof routing.baseUrl !== "string") return {};
+  try {
+    return { credentialOrigin: new URL(routing.baseUrl).origin };
+  } catch {
+    return {};
+  }
+}
+
 function namedEndpoint(raw: Record<string, unknown> | null): string | null {
   if (!raw || typeof raw.provider !== "string" || !(JEV_PROVIDER_KINDS as readonly string[]).includes(raw.provider)) return null;
-  const routing: Record<string, unknown> = { provider: raw.provider, apiKey: ENV_KEY_STAND_IN, mode: "shadow" };
+  const routing: Record<string, unknown> = { provider: raw.provider, apiKey: ENV_KEY_STAND_IN, mode: "shadow", ...displayOnlyCloudOrigin(raw) };
   if (raw.baseUrl !== undefined) routing.baseUrl = raw.baseUrl;
   if (raw.accountId !== undefined) routing.accountId = raw.accountId;
   try {
@@ -879,8 +1413,23 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
 
   if (asJson) {
     const base: Record<string, unknown> = { path: inspection.path, status: inspection.status, legacyOverride: legacy, stats };
+    // The absent text says whether this machine's key already carries Jev.
+    if (inspection.status === "absent") Object.assign(base, cloudConnection());
     if (inspection.status === "refused") {
       Object.assign(base, { reason: inspection.reason, problem: inspection.problem, permissions: octal(inspection.mode) });
+      if (inspection.fix) base.fix = inspection.fix;
+      // `permissions` is jev.json's; a refusal about credentials.json says its own.
+      if (inspection.credentialsMode !== undefined) base.credentialsPermissions = octal(inspection.credentialsMode);
+      // Known whatever the file says, or whether it parses at all.
+      Object.assign(base, cloudConnection());
+      if (readJevConfigFileForUpdate()?.raw?.provider === JEV_CLOUD_PROVIDER) {
+        Object.assign(base, {
+          provider: JEV_CLOUD_PROVIDER,
+          providerLabel: providerLabel(JEV_CLOUD_PROVIDER),
+          keySource: "cloud",
+          keySourceLabel: CLOUD_KEY_SOURCE,
+        });
+      }
       if (inspection.reason === "too-open") {
         const named = namedEndpoint(readJevConfigFileForUpdate()?.raw ?? null);
         if (named) base.endpoint = named;
@@ -894,6 +1443,7 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
       Object.assign(base, {
         permissions: octal(inspection.mode),
         provider: inspection.routing.provider,
+        providerLabel: providerLabel(inspection.routing.provider),
         ...(route ? { endpoint: displayEndpoint(route.endpoint), model: route.model, modelIsDefault: route.modelIsDefault } : {}),
         mode: inspection.routing.mode,
         timeoutMs: inspection.routing.timeoutMs,
@@ -903,18 +1453,42 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
         problem: inspection.problem,
       });
     }
+    if (inspection.status === "off" || inspection.status === "not-connected" || inspection.status === "key-lacks-jev") {
+      // Configured and deliberately (off) or circumstantially (not connected,
+      // or connected with a key that has no Jev) not running. The routing is
+      // reported exactly as for `ok`, so a provisioning check can tell any of
+      // them from a file it should rewrite.
+      const r = inspection.routing;
+      const route = routeForRouting(r);
+      const cloud = r.provider === JEV_CLOUD_PROVIDER;
+      Object.assign(base, {
+        permissions: octal(inspection.mode),
+        provider: r.provider,
+        providerLabel: providerLabel(r.provider),
+        ...(route ? { endpoint: shownEndpoint(r.provider, route.endpoint), model: route.model, modelIsDefault: route.modelIsDefault } : {}),
+        mode: r.mode,
+        timeoutMs: r.timeoutMs,
+        // Read from the credentials file rather than inferred from the status:
+        // `off` is decided before any key is looked for, so it says nothing
+        // about the connection either way.
+        ...(cloud ? { keySource: "cloud", keySourceLabel: CLOUD_KEY_SOURCE, ...cloudConnection() } : {}),
+        ...(inspection.status === "off" ? { reason: "switched-off" } : { reason: inspection.status, problem: inspection.problem }),
+      });
+    }
     if (inspection.status === "ok") {
       const { config: cfg } = inspection;
       const route = jevRoute(cfg);
       Object.assign(base, {
         permissions: octal(inspection.mode),
         provider: cfg.provider,
-        endpoint: displayEndpoint(route.endpoint),
+        providerLabel: providerLabel(cfg.provider),
+        endpoint: shownEndpoint(cfg.provider, route.endpoint),
         model: route.model,
         modelIsDefault: route.modelIsDefault,
         mode: cfg.mode,
         timeoutMs: cfg.timeoutMs,
         keySource: inspection.keySource,
+        ...(inspection.keySource === "cloud" ? { keySourceLabel: CLOUD_KEY_SOURCE, cloudConnected: true, keyCarriesJev: true } : {}),
         // How much of this machine's policy set Jev is allowed to clear, and
         // why it is none when it is none. A provisioning check that turns Jev
         // on has no other way to find out that the half it turned on cannot
@@ -957,6 +1531,12 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
           },
           opts,
         ),
+        note(
+          cloudCredentialPresent()
+            ? "Or through FailproofAI Cloud, on your org's plan — this machine's key already carries jev:evaluate: failproofai jev setup --provider failproofai"
+            : "Or through FailproofAI Cloud, on your org's plan, with no key of your own: connect with a key that carries jev:evaluate (the \"machine\" preset) — failproofai config --token <key>",
+          opts,
+        ),
         jevStatsLines(stats, opts),
       ),
     );
@@ -999,24 +1579,116 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
     );
   }
 
+  if (inspection.status === "off") {
+    // Switched off, not broken and not absent: the file is kept so switching
+    // back on needs no key and no endpoint re-typed. Said as "off" first,
+    // because that is the whole answer to "is Jev running?".
+    const r = inspection.routing;
+    const route = routeForRouting(r);
+    return ok(
+      stack(
+        title("failproofai jev status", "off (switched off)", opts),
+        note(`Jev is switched off in ${inspection.path}: it is not asked about any tool call, and hooks run the regex policies exactly as before.`, opts),
+        rows(
+          [
+            ["provider", providerLabel(r.provider)],
+            ...((route ? [["endpoint", shownEndpoint(r.provider, route.endpoint)]] : []) as Array<[string, string]>),
+            ["mode", modeLine("off")],
+            ["config", inspection.path],
+            ...((r.provider === JEV_CLOUD_PROVIDER ? [["key", cloudKeyRow()]] : []) as Array<[string, string]>),
+          ],
+          opts,
+        ),
+        nextStep("failproofai jev setup --mode shadow", "Switch it back on (shadow logs Jev and keeps enforcing regex; enforce lets it clear), here or from the dashboard:", opts),
+        legacyNote,
+        jevStatsLines(stats, opts),
+      ),
+    );
+  }
+
+  if (inspection.status === "not-connected") {
+    // The Cloud route's `key-missing`: nothing is wrong with the file, and the
+    // remedy is the connection, not a rewrite.
+    const r = inspection.routing;
+    const route = routeForRouting(r);
+    return ok(
+      stack(
+        title("failproofai jev status", "off — this machine is not connected to FailproofAI Cloud", opts),
+        note(
+          `Jev is off: ${inspection.path} sends Jev requests through FailproofAI Cloud, and this machine holds no FailproofAI Cloud key that carries jev:evaluate. ` +
+            "Hooks run the regex policies exactly as before.",
+          opts,
+        ),
+        rows(
+          [
+            ["provider", providerLabel(r.provider)],
+            ...((route ? [["endpoint", shownEndpoint(r.provider, route.endpoint)]] : []) as Array<[string, string]>),
+            ["mode", modeLine(r.mode ?? DEFAULT_JEV_MODE)],
+            ["config", inspection.path],
+            ["key", `${CLOUD_KEY_SOURCE} — not connected`],
+          ],
+          opts,
+        ),
+        nextStep(
+          "failproofai config --token <key>",
+          "Connect with a key that carries jev:evaluate (the \"machine\" preset on the dashboard's Keys page):",
+          opts,
+        ),
+        nextStep("failproofai jev remove", "Or switch Jev off:", opts),
+        legacyNote,
+        jevStatsLines(stats, opts),
+      ),
+    );
+  }
+
+  if (inspection.status === "key-lacks-jev") {
+    // Connected, so "not connected" would be false and send its owner to
+    // reconnect with the same key. The remedy is a key WITH Jev.
+    const r = inspection.routing;
+    const route = routeForRouting(r);
+    return ok(
+      stack(
+        title("failproofai jev status", KEY_LACKS_JEV_TITLE, opts),
+        note(
+          `Jev is off: ${inspection.path} sends Jev requests through FailproofAI Cloud, and no Jev key is stored for this machine's connection: its key lacks jev:evaluate, or the last connect could not confirm that. ` +
+            "Hooks run the regex policies exactly as before.",
+          opts,
+        ),
+        rows(
+          [
+            ["provider", providerLabel(r.provider)],
+            ...((route ? [["endpoint", shownEndpoint(r.provider, route.endpoint)]] : []) as Array<[string, string]>),
+            ["mode", modeLine(r.mode ?? DEFAULT_JEV_MODE)],
+            ["config", inspection.path],
+            ["key", `${CLOUD_KEY_SOURCE} — connected, no Jev key stored for it`],
+          ],
+          opts,
+        ),
+        nextStep(
+          "failproofai config --token <key>",
+          "Reconnect with this machine's key to re-check what it carries (a key without jev:evaluate needs the \"machine\" preset on the dashboard's Keys page):",
+          opts,
+        ),
+        nextStep("failproofai jev setup --mode off", "Or keep Jev off for good:", opts),
+        legacyNote,
+        jevStatsLines(stats, opts),
+      ),
+    );
+  }
+
   if (inspection.status === "refused") {
     // A file other users could change may name an endpoint its owner never
     // chose, and `chmod 600` would start trusting it with the key — so say
     // where it points before suggesting that.
-    const named = inspection.reason === "too-open" ? namedEndpoint(readJevConfigFileForUpdate()?.raw ?? null) : null;
+    const raw = readJevConfigFileForUpdate()?.raw ?? null;
+    const named = inspection.reason === "too-open" ? namedEndpoint(raw) : null;
+    const next = refusedNextStep(inspection, cloudRoute(raw));
     return fail(
       stack(
         title("failproofai jev status", "off (config refused)", opts),
         warning([`Jev is off: ${inspection.path} was refused — ${inspection.problem}.`, "Hooks run the regex policies exactly as before."], opts),
         named ? rows([["endpoint it names", named]], opts) : null,
-        inspection.reason === "too-open"
-          ? nextStep(
-              // Either the file or the directory it sits in; `fix` says which.
-              inspection.fix ?? `chmod 600 ${inspection.path}`,
-              "Other users could change this file, so check that endpoint is one you chose. Then make it owner-only (or re-run `failproofai jev setup`, which asks for the key again unless the endpoint is the provider's own):",
-              opts,
-            )
-          : nextStep("failproofai jev setup --provider <kind> --key-stdin", "Write a valid one:", opts),
+        nextStep(next.cmd, next.lead, opts),
         legacyNote,
         jevStatsLines(stats, opts),
       ),
@@ -1031,14 +1703,21 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
       title("failproofai jev status", legacy ? "on (legacy override in this shell)" : `on · ${mode}`, opts),
       rows(
         [
-          ["provider", cfg.provider],
-          ["endpoint", displayEndpoint(route.endpoint)],
+          ["provider", providerLabel(cfg.provider)],
+          ["endpoint", shownEndpoint(cfg.provider, route.endpoint)],
           ["model", route.modelIsDefault ? `${route.model} (provider default)` : route.model],
           ["mode", modeLine(mode)],
           ["timeout", `${cfg.timeoutMs} ms`],
           ["config", inspection.path],
           ["permissions", permissions(inspection.mode)],
-          ["key", inspection.keySource === "file" ? "set in the config file" : `from ${JEV_API_KEY_ENV} (this shell only; the daemon does not see it)`],
+          [
+            "key",
+            inspection.keySource === "cloud"
+              ? CLOUD_KEY_SOURCE
+              : inspection.keySource === "file"
+                ? "set in the config file"
+                : `from ${JEV_API_KEY_ENV} (this shell only; the daemon does not see it)`,
+          ],
         ],
         opts,
       ),
@@ -1079,19 +1758,51 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
         ? `There is no ${inspection.path}; nothing to test.`
         : inspection.status === "key-missing"
           ? `${inspection.path} takes its key from ${JEV_API_KEY_ENV}, which is not set in this shell, so there is no key to test with.`
-          : `${inspection.path} was refused — ${inspection.problem}.`;
-    const code = inspection.status === "absent" ? "not-configured" : inspection.status === "key-missing" ? "no-env-key" : "config";
-    const fixCmd =
-      inspection.status === "key-missing" ? "failproofai jev setup --key-stdin < key-file" : "failproofai jev setup --provider <kind> --key-stdin";
+          : inspection.status === "off"
+            ? `Jev is switched off in ${inspection.path} (mode off), so nothing is sent.`
+            : inspection.status === "not-connected"
+              ? `${inspection.path} sends Jev requests through FailproofAI Cloud, and this machine is not connected to it with a key that carries jev:evaluate.`
+              : inspection.status === "key-lacks-jev"
+                ? `${inspection.path} sends Jev requests through FailproofAI Cloud, and no Jev key is stored for this machine's connection.`
+                : `${inspection.path} was refused — ${inspection.problem}.`;
+    const code =
+      inspection.status === "absent"
+        ? "not-configured"
+        : inspection.status === "key-missing"
+          ? "no-env-key"
+          : inspection.status === "off"
+            ? "switched-off"
+            : inspection.status === "not-connected" || inspection.status === "key-lacks-jev"
+              ? inspection.status
+              : "config";
+    const refusedNext =
+      inspection.status === "refused"
+        ? refusedNextStep(inspection, cloudRoute(readJevConfigFileForUpdate()?.raw))
+        : inspection.status === "absent" && cloudCredentialPresent()
+          ? { cmd: "failproofai jev setup --provider failproofai", lead: "This machine's FailproofAI Cloud key already carries jev:evaluate. Turn it on:" }
+          : null;
+    const fixCmd = refusedNext
+      ? refusedNext.cmd
+      : inspection.status === "key-missing"
+        ? "failproofai jev setup --key-stdin < key-file"
+        : inspection.status === "off"
+          ? "failproofai jev setup --mode shadow"
+          : inspection.status === "not-connected" || inspection.status === "key-lacks-jev"
+            ? "failproofai config --token <key>"
+            : "failproofai jev setup --provider <kind> --key-stdin";
+    const fixLead = refusedNext
+      ? refusedNext.lead
+      : inspection.status === "key-missing"
+        ? `Set ${JEV_API_KEY_ENV} for this shell, or store the key in the file:`
+        : inspection.status === "off"
+          ? "Switch it back on:"
+          : inspection.status === "not-connected"
+            ? "Connect with a key that carries jev:evaluate:"
+            : inspection.status === "key-lacks-jev"
+              ? "Reconnect with this machine's key to re-check what it carries (a key without jev:evaluate needs the \"machine\" preset on the dashboard's Keys page):"
+              : undefined;
     const json = asJson ? JSON.stringify({ ok: false, error: { code, message: why } }, null, 2) : undefined;
-    return fail(
-      stack(
-        title("failproofai jev test", "not run", opts),
-        note(why, opts),
-        nextStep(fixCmd, inspection.status === "key-missing" ? `Set ${JEV_API_KEY_ENV} for this shell, or store the key in the file:` : undefined, opts),
-      ),
-      json,
-    );
+    return fail(stack(title("failproofai jev test", "not run", opts), note(why, opts), nextStep(fixCmd, fixLead, opts)), json);
   }
 
   const cfg = inspection.config;
@@ -1119,12 +1830,16 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
     const within = latencyMs <= budget;
     const p = answers[JEV_TEST_QUESTION_ID];
     const inputTokens = typeof response.usage?.input_tokens === "number" ? response.usage.input_tokens : null;
+    // "ok" means a hook would use this answer: in time, and right about "blue".
+    const problem = !within ? "over-timeout" : p < 0.5 ? "unexpected-answer" : null;
+    const done = problem ? fail : ok;
     if (asJson) {
-      return ok(
+      return done(
         [],
         JSON.stringify(
           {
-            ok: true,
+            ok: problem === null,
+            ...(problem ? { problem } : {}),
             provider: cfg.provider,
             endpoint: displayEndpoint(route.endpoint),
             model: built.model,
@@ -1141,9 +1856,11 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
         ),
       );
     }
-    return ok(
+    const status =
+      problem === "over-timeout" ? `over timeout · ${latencyMs} ms` : problem ? `wrong answer · p = ${p.toFixed(3)}` : `ok · ${latencyMs} ms`;
+    return done(
       stack(
-        title("failproofai jev test", `ok · ${latencyMs} ms`, opts),
+        title("failproofai jev test", status, opts),
         rows(
           [
             ["provider", cfg.provider],
@@ -1163,6 +1880,9 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
           "One request, sent directly: the hook path's cache and rate limit were not involved, and a fresh process pays DNS and TLS setup that the daemon's warm worker does not.",
           opts,
         ),
+        problem === "over-timeout"
+          ? nextStep("failproofai jev setup --timeout-ms <n>", `Give hooks longer (up to ${MAX_JEV_TIMEOUT_MS} ms), or use a faster route:`, opts)
+          : null,
       ),
     );
   } catch (err) {
@@ -1170,7 +1890,10 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
     // jev-client scrubs provider text already; this is the last line of that
     // defence, for any error text that reached here some other way.
     const e = scrubbed(describeError(err), cfg.apiKey);
-    if (asJson) return fail([], JSON.stringify({ ok: false, provider: cfg.provider, latencyMs, error: e }, null, 2));
+    // An answer after the hook budget is a `timeout` to every hook, whatever it
+    // finally said (a Cloud route maps its own upstream timeout to 502).
+    const late = latencyMs > budget;
+    if (asJson) return fail([], JSON.stringify({ ok: false, provider: cfg.provider, latencyMs, timeoutMs: budget, withinTimeout: !late, error: e }, null, 2));
     return fail(
       stack(
         title("failproofai jev test", `failed · ${e.code}`, opts),
@@ -1180,14 +1903,212 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
             ["endpoint", displayEndpoint(route.endpoint)],
             ["model asked", built.model],
             ["error", `${e.code}: ${e.message}`],
-            ["after", `${latencyMs} ms`],
+            ["after", late ? `${latencyMs} ms — OVER the ${budget} ms timeout: hooks would fall back to regex (timeout)` : `${latencyMs} ms`],
+          ],
+          opts,
+        ),
+        note(
+          late
+            ? `Hooks stop waiting after ${budget} ms, so they record this as \`timeout\`, not ${e.code}: the provider or FailproofAI Cloud is slow or failing upstream.`
+            : remedy(e.code, cfg.provider, e.message),
+          opts,
+        ),
+      ),
+    );
+  }
+}
+
+// ── models ───────────────────────────────────────────────────────────────────
+
+/** What a shape means, which decides what the names in it can be used for. */
+function shapeMeans(shape: JevModelListRead["shape"]): string {
+  return shape === "typesafe"
+    ? "TypeSafe's own inventory — the aliases <base>/systemone answers to; versioned ids such as jev-1.13.0 are accepted without being listed"
+    : "an OpenAI-shaped gateway catalog — it lists what the gateway serves, not what <base>/systemone answers to, so it is shown and never used to refuse a model";
+}
+
+/**
+ * `failproofai jev models` — what `GET <base>/models` says an endpoint serves.
+ *
+ * The question a person asks after `jev test` fails, and the one the LiteLLM-proxy
+ * customer answered by curling the endpoint by hand. With no flags it asks the
+ * configured route; `--provider` asks a provider's own API and `--url` any base.
+ *
+ * The stored key is sent only to the origin it was stored for. `--url` takes a URL
+ * off the command line, and a key issued for one gateway must not go to another
+ * because a diagnostic named it — the same rule `setup` applies when a new
+ * `--base-url` moves the host. Vercel's and OpenRouter's lists are public, so an
+ * unkeyed read is often still an answer, and the output says which it was.
+ */
+async function models(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise<JevCliResult> {
+  // The same test the launcher uses to print `json` instead of the lines, so a
+  // refusal made before the flags parse is JSON as well: every `--json` outcome
+  // is an object, as `jev test --json`'s are.
+  const asJson = argv.includes("--json");
+  const refuse = (code: string, lines: string[]) =>
+    fail(lines, asJson ? JSON.stringify({ ok: false, error: { code, message: lines.join("\n") } }, null, 2) : undefined);
+  const parsed = parseFlags(argv, new Set(["--json", "--provider", "--url"]));
+  if (typeof parsed === "string") return refuse("usage", [parsed, "", ...JEV_USAGE]);
+  if (parsed.positionals.length > 0) return refuse("usage", [STRAY_ARGUMENT, "", ...JEV_USAGE]);
+  const { values } = parsed;
+
+  // Checked before anything else uses it, and never echoed — the same rule
+  // `setup` follows, for the same reason: the likeliest wrong value is a key.
+  const named = values.get("--provider");
+  if (named !== undefined && !(JEV_PROVIDER_KINDS as readonly string[]).includes(named)) {
+    return refuse("unknown-provider", [
+      "Unknown provider (not repeated here, in case it is a key).",
+      `Providers: ${JEV_PROVIDER_KINDS.join(", ")} — exactly as spelled here, lower-case.`,
+    ]);
+  }
+
+  // The configured route, for the default base, for the key, and for the model to
+  // mark. `key-missing` counts: the file's routing is sound, it just has no key
+  // here, and a public list answers anyway.
+  const inspection = inspectJevConfig();
+  const routing: Omit<JevConfig, "apiKey"> | null =
+    inspection.status === "ok"
+      ? inspection.config
+      : inspection.status === "key-missing" ||
+          inspection.status === "off" ||
+          inspection.status === "not-connected" ||
+          inspection.status === "key-lacks-jev"
+        ? inspection.routing
+        : null;
+  const storedKey = inspection.status === "ok" ? inspection.config.apiKey : null;
+
+  let provider: JevProviderKind;
+  let base: string | null;
+  const urlArg = values.get("--url");
+  if (urlArg !== undefined) {
+    const checked = validateBaseUrl(urlArg);
+    if (!checked.ok) return refuse("bad-url", [`Cannot read a model list: ${checked.problem}.`]);
+    const asEndpoint = endpointGivenAsBase(checked.value);
+    if (asEndpoint) return refuse("endpoint-as-base", endpointAsBaseRefusal("--url", checked.value, asEndpoint));
+    base = checked.value;
+    provider = (named as JevProviderKind | undefined) ?? providerForUrl(base);
+  } else if (named !== undefined) {
+    provider = named as JevProviderKind;
+    base = JEV_PROVIDER_DEFAULTS[provider].baseUrl;
+    if (base === null && provider === JEV_CLOUD_PROVIDER) {
+      return refuse("no-model-list", [
+        `FailproofAI Cloud serves no model list: it runs ${JEV_PROVIDER_DEFAULTS.failproofai.model}, pinned on the server, and every answer is checked against the Jev 1.13 family.`,
+      ]);
+    }
+    if (base === null) {
+      return refuse("no-api", ["Provider custom has no API of its own — its URL is the whole address.", "  failproofai jev models --url <base>"]);
+    }
+  } else if (routing !== null) {
+    provider = routing.provider;
+    base = routing.baseUrl ?? JEV_PROVIDER_DEFAULTS[routing.provider].baseUrl;
+  } else {
+    return refuse("not-configured", [
+      `Jev is not configured here (no ${inspection.path}), so there is no endpoint to ask.`,
+      "Name one:",
+      "  failproofai jev models --provider vercel",
+      "  failproofai jev models --url https://your-proxy.example.com/typesafe/v1",
+    ]);
+  }
+
+  // Cloudflare is the one route with no `<base>/models`: Workers AI runs models at
+  // `/accounts/<id>/ai/run` and keeps its inventory behind a different API, so
+  // there is nothing here to read rather than something that failed to read.
+  // FailproofAI Cloud serves no list either: it pins the model server-side
+  // (`jev-1.13.0`), so there is nothing to choose and nothing to read.
+  const modelsUrl = provider === "cloudflare" || provider === JEV_CLOUD_PROVIDER || base === null ? null : modelsUrlForBase(base);
+  if (modelsUrl === null) {
+    return refuse("no-model-list", [
+      provider === "cloudflare"
+        ? "Cloudflare Workers AI serves no <base>/models: its models are listed through the Cloudflare API, not through the Jev base URL."
+        : provider === JEV_CLOUD_PROVIDER
+          ? `FailproofAI Cloud serves no model list: it runs ${JEV_PROVIDER_DEFAULTS.failproofai.model}, pinned on the server, and every answer is checked against the Jev 1.13 family.`
+          : "That base URL names no endpoint a model list could be read from.",
+    ]);
+  }
+
+  const askOrigin = originOf(provider, base);
+  const configuredOrigin = routing !== null ? originOf(routing.provider, routing.baseUrl) : null;
+  const sameOrigin = askOrigin !== null && askOrigin === configuredOrigin;
+  const apiKey = sameOrigin ? storedKey : null;
+  // Only meaningful for the route that is actually configured: marking a name on
+  // some other host as "configured" would be saying something untrue.
+  const configuredModel = sameOrigin && routing !== null ? (routing.model ?? JEV_PROVIDER_DEFAULTS[routing.provider].model) : null;
+
+  let list: JevModelListResult;
+  try {
+    list = await (deps.readModelList ?? liveModelListReader)(modelsUrl, apiKey);
+  } catch (err) {
+    list = { ok: false, reason: scrubSecret(err instanceof Error ? err.message : String(err), apiKey ?? "") };
+  }
+
+  const shown = displayEndpoint(modelsUrl);
+  const keyNote = apiKey
+    ? "the configured key for this origin"
+    : sameOrigin
+      ? `none stored here — set ${JEV_API_KEY_ENV}, or store one with \`failproofai jev setup --key-stdin\``
+      : storedKey !== null
+        ? "none sent: a stored key belongs to the endpoint it was stored for"
+        : "none: nothing is configured for this endpoint, and some lists are public";
+
+  if (!list.ok) {
+    if (asJson) {
+      return fail([], JSON.stringify({ ok: false, provider, endpoint: shown, error: { code: "model-list-unread", message: list.reason } }, null, 2));
+    }
+    return fail(
+      stack(
+        title("failproofai jev models", "not read", opts),
+        rows(
+          [
+            ["provider", provider],
+            ["endpoint", shown],
+            ["key", keyNote],
+            ["reason", list.reason],
           ],
           opts,
         ),
-        note(remedy(e.code), opts),
+        note(
+          "Not every endpoint serves a model list — a proxy may expose only /systemone — and nothing depends on one: setup and hooks work without it.",
+          opts,
+        ),
       ),
     );
   }
+
+  if (asJson) {
+    return ok(
+      [],
+      JSON.stringify({ ok: true, provider, endpoint: shown, shape: list.shape, models: list.models, configuredModel, keySent: apiKey !== null }, null, 2),
+    );
+  }
+  const listed = list.models.slice(0, MAX_SHOWN_MODELS);
+  return ok(
+    stack(
+      title("failproofai jev models", `${list.models.length} · ${provider}`, opts),
+      rows(
+        [
+          ["provider", provider],
+          ["endpoint", shown],
+          ["key", keyNote],
+          ["list", shapeMeans(list.shape)],
+        ],
+        opts,
+      ),
+      rows(
+        listed.map((name) => [name, name === configuredModel ? "configured" : ""] as [string, string]),
+        opts,
+      ),
+      list.models.length > listed.length ? note(`… and ${list.models.length - listed.length} more.`, opts) : null,
+      configuredModel !== null && !modelListHasModel(list, configuredModel) && listDescribesSystemOne(list)
+        ? warning(
+            [
+              `The configured model ${configuredModel} is not one of these, so every evaluation would fail at this endpoint and hooks would fall back to regex.`,
+              `Point it at one of them: failproofai jev setup --model ${list.models[0]}`,
+            ],
+            opts,
+          )
+        : null,
+    ),
+  );
 }
 
 // ── remove ───────────────────────────────────────────────────────────────────
@@ -1232,6 +2153,8 @@ export async function runJevCommand(argv: string[], deps: JevCliDeps = {}): Prom
       return status(rest, opts);
     case "test":
       return test(rest, deps, opts);
+    case "models":
+      return models(rest, deps, opts);
     case "remove":
       return remove(rest, opts);
     default: {