failproofai 1.0.12-beta.0 → 1.0.12-beta.2

package/src/hooks/manager.ts

@@ -32,7 +32,9 @@ import { getInstanceId, hashToId } from "../../lib/telemetry-id";
 import { CliError } from "../cli-error";
 import { hookLogWarn } from "./hook-logger";
 import { customPoliciesDir } from "./fp-home";
-import { readActiveCloudManagedPolicies } from "./cloud-managed-policies";
+import { listActiveCloudManagedPolicies, readCloudJevAssignments, readCloudJevState, type CloudJevMode } from "./cloud-managed-policies";
+import { readCloudPolicyErrors } from "./cloud-policy-errors";
+import { readRosterLabels } from "./agent-roster";
 import { CORE_SOURCE, addPack, setPackPolicyEnabled } from "./pack-store";
 import type { ResolvedPack } from "./pack-manifest";
 import { hasInstalledRegexPacks, readInstalledPacks } from "./pack-manifest";
@@ -332,6 +334,35 @@ export function integrationsInstalledAt(scope: HookScope, cwd?: string): Integra
  */
 export type NotEnforcingReason = "no-hooks" | "no-policies" | "observe-only";
 
+/** Machine-wide assignments, like the listing: a `both` policy counts once. */
+function cloudPolicyStatus(): { count: number; observing: boolean } {
+  let count = 0;
+  let observing = false;
+  const jsIds = new Set<string>();
+  try {
+    for (const artifact of listActiveCloudManagedPolicies()) {
+      jsIds.add(artifact.id);
+      if (artifact.effect === "observe") observing = true;
+      else count++;
+    }
+  } catch {
+    // The listing reports an unreadable JS deployment; Jev is read independently.
+  }
+  try {
+    const { jevMode } = readCloudJevState();
+    if (jevMode === "enforce" || jevMode === "observe") {
+      for (const assignment of readCloudJevAssignments() ?? []) {
+        if (jsIds.has(assignment.id)) continue;
+        if (jevMode === "observe" || assignment.effect === "observe") observing = true;
+        else count++;
+      }
+    }
+  } catch {
+    // No readable Jev state: neither enforcement nor observation is known.
+  }
+  return { count, observing };
+}
+
 export function notEnforcingReason(cwd?: string): NotEnforcingReason | null {
   const wired = deduplicateScopes(HOOK_SCOPES, cwd).some((scope) => hooksInstalledInSettings(scope, cwd));
   if (!wired) return "no-hooks";
@@ -361,15 +392,11 @@ export function notEnforcingReason(cwd?: string): NotEnforcingReason | null {
     // An unreadable manifest is reported by the listing itself.
   }
 
-  // Cloud-managed policies, pushed from a deployment.
-  try {
-    for (const artifact of readActiveCloudManagedPolicies()) {
-      if (artifact.effect === "observe") observing = true;
-      else return null;
-    }
-  } catch {
-    // No deployment, or an unreadable one: nothing enforces from there.
-  }
+  // Cloud JS enforces independently of Jev mode. Jev-only assignments enforce
+  // only in Cloud's enforce mode, and watch only while Jev is not off.
+  const cloud = cloudPolicyStatus();
+  if (cloud.count > 0) return null;
+  observing ||= cloud.observing;
 
   // A configured custom policy file, or convention files on disk. Loading them
   // to ask what they hold would import user code on every launch, so their
@@ -390,10 +417,11 @@ export function notEnforcingReason(cwd?: string): NotEnforcingReason | null {
  * How many policies enforce on this machine, for the line that says so.
  *
  * Counted the same way `notEnforcingReason` decides, so the two never disagree:
- * pack policies that are taken and not switched off, cloud-managed policies, and
- * the legacy builtins of a machine still on the migration shim — observe-only
- * ones excluded. Custom policy files cannot be counted without importing them,
- * so their presence is reported on its own.
+ * pack policies that are taken and not switched off, Cloud JS policies and
+ * Jev-only assignments in Cloud's enforce mode, and the legacy builtins of a
+ * machine still on the migration shim — observe-only ones excluded, `both`
+ * assignments counted once. Custom policy files cannot be counted without
+ * importing them, so their presence is reported on its own.
  */
 export function enforcingPolicyCount(cwd?: string): { count: number; custom: boolean } {
   const config = readMergedHooksConfig(cwd);
@@ -408,13 +436,7 @@ export function enforcingPolicyCount(cwd?: string): { count: number; custom: boo
   } catch {
     // An unreadable manifest counts nothing, as it enforces nothing.
   }
-  try {
-    for (const artifact of readActiveCloudManagedPolicies()) {
-      if (artifact.effect !== "observe") count++;
-    }
-  } catch {
-    // No deployment.
-  }
+  count += cloudPolicyStatus().count;
   if (!hasInstalledRegexPacks()) count += config.enabledPolicies.length;
   const projectDir = resolve(findProjectConfigDir(cwd ?? process.cwd()), ".failproofai", "policies");
   const custom =
@@ -1245,7 +1267,16 @@ export interface PoliciesScreen {
   attention: { failed: boolean; text: string; fix?: string } | null;
   custom: PoliciesScreenRow[];
   convention: Array<{ scope: string; rows: PoliciesScreenRow[] }>;
-  cloud: { deployment: number; rows: PoliciesScreenRow[] } | null;
+  cloud: {
+    deployment: number | null;
+    rows: PoliciesScreenRow[];
+    /** FailproofAI Cloud's Jev mode for this machine, when the deployment sets one. */
+    jevMode?: CloudJevMode | null;
+    /** Problems reading the deployment, each one line. */
+    problems?: string[];
+    /** The manifest names its Jev assignments (`jevPolicies`), so Jev-only policies are among `rows`. */
+    jevListed?: boolean;
+  } | null;
   /**
    * Builtins this build enforces itself because no pack is installed: the
    * migration shim (`handler.ts` registers `enabledPolicies` when
@@ -1376,7 +1407,22 @@ export function renderPoliciesScreen(
   }
   if (screen.custom.length > 0) plain("Custom policies", undefined, screen.custom);
   for (const { scope, rows } of screen.convention) plain("Convention policies", scope, rows);
-  if (screen.cloud) plain("Cloud-managed", `deployment ${screen.cloud.deployment}`, screen.cloud.rows);
+  if (screen.cloud) {
+    const { deployment, rows, jevMode, problems } = screen.cloud;
+    plain("Cloud-managed", deployment !== null ? `deployment ${deployment}` : undefined, rows);
+    if (jevMode === "off") {
+      out.push(`${INDENT}Jev mode: off, set by FailproofAI Cloud (overrides jev.json).`);
+    } else if (jevMode) {
+      out.push(`${INDENT}Jev mode: ${jevMode}, set by FailproofAI Cloud. Jev checks run on FailproofAI Cloud; nothing of them is installed here.`);
+      // A manifest from a server that predates `jevPolicies` does not name its
+      // Jev-only policies: say so, or an empty section reads as "Cloud
+      // deployed nothing".
+      if (!screen.cloud.jevListed) {
+        out.push(`${INDENT}Jev-only Cloud policies are not listed here; see them with ${kit.cmd("fp fleet show")} or on the dashboard.`);
+      }
+    }
+    for (const problem of problems ?? []) out.push(kit.caution(problem));
+  }
 
   if (folded > 0) out.push("", `See all ${total} with ${kit.cmd("failproofai policies --all")}`);
   return out;
@@ -1591,20 +1637,114 @@ export async function listHooks(cwd?: string, { all = false }: { all?: boolean }
   // pushed to a fleet were the ones invisible to the person running the
   // command on it. Read-only: they belong to the deployment, which the heading
   // says, and `--uninstall <name>` cannot switch one off.
+  //
+  // Each policy's KIND is shown — `regex` (JS) or `both` (JS whose verdict
+  // its own Jev checks may clear) — with the Jev check names a `both` policy
+  // is reviewed by. Those checks, and every `jev` policy, run on FailproofAI
+  // Cloud (CONTRACT C10): no question is on this machine, but the manifest's
+  // `jevPolicies` names each Jev assignment, so a Jev-only policy gets a row
+  // (tagged `jev`) like the JS ones.
   let cloud: PoliciesScreen["cloud"] = null;
   try {
-    const active = readActiveCloudManagedPolicies();
-    if (active.length > 0) {
+    // Every assignment, agent-scoped ones included (B4): this lists the
+    // machine's deployment, not what one hook would load.
+    let active: ReturnType<typeof listActiveCloudManagedPolicies> = [];
+    let jsProblem: string | null = null;
+    try {
+      active = listActiveCloudManagedPolicies();
+    } catch (err) {
+      // The Jev mode is read independently below; a machine Cloud set one on
+      // still gets its section, with this said.
+      jsProblem = err instanceof Error ? err.message : String(err);
+    }
+    let jev: ReturnType<typeof readCloudJevState> = { jevMode: null, deployment: null, errors: [] };
+    try {
+      jev = readCloudJevState();
+    } catch {
+      // Never throws by contract; guarded anyway, for the same reason as above.
+    }
+    // A Cloud JS policy that did not load (B5): the hook path records it in
+    // errors.json for the deployment in force, so the row says "not loaded"
+    // rather than ● on.
+    const loadErrors = new Map<string, string>();
+    try {
+      for (const e of readCloudPolicyErrors() ?? []) {
+        if (e.kind !== "regex" && e.kind !== "both") continue;
+        const artifact = active.find((a) => a.id === e.id);
+        if (artifact && (e.version === null || e.version === artifact.version)) loadErrors.set(e.id, e.message);
+      }
+    } catch {
+      // No report: every row reads as the deployment says.
+    }
+    // A policy deployed here is drawn ● on. Only the hook path imports Cloud
+    // JavaScript, so one that fails to load is known only after a tool call,
+    // and then shows as not loaded (errors.json, above) — never as a transient
+    // "not loaded yet" state of its own.
+    // Jev-only assignments (`jevPolicies`): ids, versions, effects and scopes,
+    // never a question. A `both` policy is in both lists and is drawn once,
+    // from its JS row. Null from a server that predates the list.
+    let jevAssignments: ReturnType<typeof readCloudJevAssignments> = null;
+    try {
+      jevAssignments = readCloudJevAssignments();
+    } catch {
+      // Never throws by contract.
+    }
+    const jsIds = new Set(active.map((a) => a.id));
+    const jevOnly = (jevAssignments ?? []).filter((a) => !jsIds.has(a.id));
+    const labels = [...active, ...jevOnly].some((a) => a.agentTargets?.some((tg) => tg.instanceId))
+      ? readRosterLabels()
+      : new Map<string, string>();
+    const targetText = (targets: NonNullable<(typeof active)[number]["agentTargets"]>): string =>
+      `for ${targets
+        .map((tg) => (tg.instanceId ? `${tg.integration} / ${labels.get(tg.instanceId) ?? tg.instanceId}` : tg.integration))
+        .join(", ")}`;
+    if (active.length > 0 || jevOnly.length > 0 || jev.jevMode !== null) {
+      const jevRows: PoliciesScreenRow[] = jevOnly.map((a) => {
+        const tags = [
+          ...(a.effect === "observe" ? ["observe"] : []),
+          "jev",
+          ...(a.agentTargets?.length ? [targetText(a.agentTargets)] : []),
+        ];
+        return { state: "on" as const, name: a.id, description: `v${a.version}`, tag: tags.join(" · ") };
+      });
       cloud = {
-        deployment: active[0].deployment,
-        rows: active.map((artifact) => ({
-          state: "on" as const,
-          name: artifact.id,
-          description: `v${artifact.version}`,
-          // `observe` is evaluated and then has its verdict discarded, so the
-          // row says so rather than reading as plain enforcement.
-          ...(artifact.effect === "observe" ? { tag: "observe" } : {}),
-        })),
+        deployment: active[0]?.deployment ?? jev.deployment ?? null,
+        jevListed: jevAssignments !== null,
+        rows: [...active.map((artifact) => {
+          // Only a `both` policy carries a server-derived reviewer list (C1).
+          const both = artifact.authority === "reviewable" && (artifact.reviewedBy?.length ?? 0) > 0;
+          const checks = both ? (artifact.reviewedBy ?? []).join(", ") : "";
+          const tags = [
+            // `observe` is evaluated and then has its verdict discarded, so the
+            // row says so rather than reading as plain enforcement.
+            ...(artifact.effect === "observe" ? ["observe"] : []),
+            // A plain JS policy stays the plain row it always was.
+            ...(both ? ["both"] : []),
+            // An observe `both` has its Jev half withheld by Cloud (C9.3).
+            ...(both ? [artifact.effect === "observe" ? `${checks} (not asked while observed)` : `Jev checks: ${checks}`] : []),
+            ...(artifact.agentTargets?.length ? [targetText(artifact.agentTargets)] : []),
+          ];
+          const failed = loadErrors.get(artifact.id);
+          if (failed !== undefined) {
+            return {
+              state: "failed" as const,
+              name: artifact.id,
+              description: `v${artifact.version}`,
+              tag: [...tags, `not loaded: ${failed}`].join(" · "),
+            };
+          }
+          return {
+            state: "on" as const,
+            name: artifact.id,
+            description: `v${artifact.version}`,
+            ...(tags.length > 0 ? { tag: tags.join(" · ") } : {}),
+          };
+        }), ...jevRows],
+        jevMode: jev.jevMode,
+        problems: [
+          ...(jsProblem !== null ? [`The Cloud JavaScript policies could not be read, so none of them is enforcing: ${jsProblem}`] : []),
+          ...jev.errors.map((e) => `${e.id}${e.version === null ? "" : ` v${e.version}`}: ${e.message}`),
+        ],
       };
     }
   } catch {

package/src/hooks/pack-failclosed.ts

@@ -54,6 +54,8 @@ export interface MissingGuard {
  */
 export const PERMANENT_LOAD_FAILURES: ReadonlySet<string> = new Set([
   "module_not_found",
+  // A data file the policy reads at load is as missing on the next call.
+  "file_not_found",
   "syntax_error",
   "runtime_error",
   "path_missing",

package/src/hooks/pack-manifest.ts

@@ -738,8 +738,15 @@ export function semanticQuestions(
  * Per ENTRY, not per pack: one malformed question set must not take the rest of
  * a publisher's semantic policies with it, for the same reason one malformed
  * pack does not take the other packs with it.
+ *
+ * Exported for one reader outside this file: the shared FailproofAI Cloud
+ * fixtures test (`cloud-jev-policies.test.ts`). A Cloud Jev declaration is
+ * exactly a manifest semantic entry, and Cloud's publish validation mirrors
+ * this parser — so the test pins that both accept and refuse the same
+ * declarations, and measure their questions alike. The machine itself never
+ * parses a Cloud declaration: those checks run on FailproofAI Cloud (C10).
  */
-function parsePackSemantic(packId: string, value: unknown, warnings: string[]): SemanticManifestEntry[] {
+export function parsePackSemantic(packId: string, value: unknown, warnings: string[]): SemanticManifestEntry[] {
   if (value === undefined) return [];
   if (!Array.isArray(value)) {
     warnings.push(`pack ${packId} semantic is not an array, so none of it was loaded`);

package/src/hooks/policy-evaluator.ts

@@ -25,6 +25,7 @@ import {
   type JevReview,
   type RegexVerdict,
   type ObserveVerdict,
+  type ObservedCloudVerdict,
   type TwoTierReview,
 } from "./semantic/combine";
 // The code, not a copy of the string: the log line below turns on it, and a
@@ -64,6 +65,8 @@ export interface EvaluationResult {
     jevOrigin?: { packId: string; packVersion?: string };
     /** Observe mode: Jev's own deny/instruct, recorded as a "would have" (see `ObserveVerdict`). */
     observeVerdict?: ObserveVerdict;
+    /** An `observe` Cloud Jev assignment's would-haves (see `JevReview.observedCloud`). */
+    observedCloud?: ReadonlyArray<ObservedCloudVerdict>;
   };
 }
 
@@ -217,6 +220,19 @@ export async function evaluatePolicies(
     twoTier.releaseRegistry?.();
     review = await twoTier.review;
   }
+  // Jev asked no check about this call (Cloud's short-circuit, or nothing
+  // selected): it took no part, so the row carries no Jev fields at all — the
+  // regex result, exactly as without a review.
+  if (review.kind === "answered" && review.asked.length === 0 && review.decision === "allow" && !review.observedAsked?.length) {
+    return formatVerdict(eventType, session, toolName, regexOnly(collected.verdicts));
+  }
+  // A hard regex deny decided before FailproofAI Cloud's Jev answered, and the
+  // request was dropped: Jev took no part, so the row is the regex (Cloud or
+  // local) policy's, with no Jev fields. A local `jev.json` keeps its
+  // `not-consulted` row, which `jev status` counts.
+  if (review.kind === "not-consulted" && twoTier.cloud) {
+    return formatVerdict(eventType, session, toolName, regexOnly(collected.verdicts));
+  }
   const combined = combineTwoTier(collected.verdicts, review, twoTier.mode);
   if (combined.cleared.length > 0) {
     hookLogInfo(`jev ${twoTier.mode === "observe" ? "would clear" : "cleared"}: ${combined.cleared.join(", ")}`);
@@ -250,8 +266,13 @@ export async function evaluatePolicies(
     twoTier: {
       activity: combined.activity,
       decidedByJev: combined.decidedByJev,
-      ...(combined.decidedByJev && review.kind === "answered" && review.origin ? { jevOrigin: review.origin } : {}),
+      // The deciding check's origin — and, in observe mode, the origin of the
+      // check that WOULD have decided (B12), so that row names its policy too.
+      ...((combined.decidedByJev || combined.observeVerdict) && review.kind === "answered" && review.origin
+        ? { jevOrigin: review.origin }
+        : {}),
       ...(combined.observeVerdict ? { observeVerdict: combined.observeVerdict } : {}),
+      ...(review.kind === "answered" && review.observedCloud?.length ? { observedCloud: review.observedCloud } : {}),
     },
   };
 }

package/src/hooks/policy-registry.ts

@@ -8,6 +8,7 @@
 import type { HookEventType } from "./types";
 import type { PolicyFunction, PolicyMatcher, PolicyParamsSchema, RegisteredPolicy } from "./policy-types";
 import { effectiveReviewerNames, forgetEffectiveReviewerNames } from "./effective-reviewers";
+import type { AgentIdentity } from "./agent-targets";
 import { resolvePolicyAuthority, type AuthorityDeclaration } from "./policy-authority";
 
 const REGISTRY_KEY = "__FAILPROOFAI_POLICY_REGISTRY__";
@@ -126,14 +127,14 @@ export function getPoliciesForEvent(
 }
 
 /** `cli`: the agent this pass registers for, which scopes the Jev reviewer set. */
-export function clearPolicies(cli?: string): void {
+export function clearPolicies(cli?: string, agent: AgentIdentity | null = null): void {
   const g = globalThis as GlobalWithRegistry;
   g[REGISTRY_KEY] = [];
   setIndexCache(null);
   // The reviewer set describes the policies that are about to be registered, so
   // it is rebuilt with them. Dropping it here is also what keeps one read per
   // evaluation instead of one per policy.
-  forgetEffectiveReviewerNames(cli);
+  forgetEffectiveReviewerNames(cli, agent);
 }
 
 /**

package/src/hooks/policy-reviewability.ts

@@ -55,7 +55,12 @@
  * - **A session pause.** It suspends local policy for minutes, and a warning
  *   about a policy set that is coming back shortly would be noise.
  */
-import { readActiveCloudManagedPolicies } from "./cloud-managed-policies";
+import {
+  cloudAuthorityDeclaration,
+  cloudReviewerNames,
+  listActiveCloudManagedPolicies,
+  readCloudJevMode,
+} from "./cloud-managed-policies";
 import { jevPacks } from "./effective-reviewers";
 import { resolve } from "node:path";
 import { discoverPolicyFiles } from "./custom-hooks-loader";
@@ -202,9 +207,17 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
   }
 
   try {
-    for (const assignment of readActiveCloudManagedPolicies()) {
-      records.push({ authority: assignment.authority, reviewedBy: assignment.reviewedBy });
-    }
+    // Exactly as `handler.ts` registers them: a `both` policy is reviewable
+    // only while FailproofAI Cloud's Jev mode asks, and then only by its own
+    // Cloud checks (`cloud:<id>/<name>`), which this machine cannot list but
+    // Cloud answers for. No mode, `off`, or an `observe` assignment: hard.
+    const mode = readCloudJevMode();
+    // Listed for every agent: this survey has no agent, and the hook-scoped
+    // read with none drops each agent-targeted assignment.
+    const assignments = listActiveCloudManagedPolicies();
+    const cloudReviewers = cloudReviewerNames(assignments, mode);
+    if (cloudReviewers.length > 0) reviewers = new Set([...(reviewers ?? []), ...cloudReviewers]);
+    for (const assignment of assignments) records.push(cloudAuthorityDeclaration(assignment, mode));
   } catch {
     // Same fail-open as the handler's own read of this file.
   }
@@ -225,7 +238,12 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
     customFiles = 0;
   }
 
-  return { ...countReviewable(records, reviewers), customFiles, jevChecks: reviewers?.size ?? 0 };
+  return {
+    ...countReviewable(records, reviewers),
+    customFiles,
+    // The checks THIS machine asks; a Cloud policy's checks are FailproofAI Cloud's.
+    jevChecks: reviewers ? [...reviewers].filter((name) => !name.startsWith("cloud:")).length : 0,
+  };
 }
 
 /**

package/src/hooks/semantic/cloud-jev-health.ts

@@ -0,0 +1,227 @@
+/**
+ * FailproofAI Cloud Jev's health as this machine sees it (review M3).
+ *
+ * Under a Cloud Jev mode every gated tool call is a Cloud call, and every one
+ * that fails falls back to the regex alone. That trade is right for the hook
+ * path, and it used to be silent. This module adds two things:
+ *
+ * - **A circuit breaker.** After {@link BREAKER_FAILURES} Cloud Jev failures
+ *   in a row (a timeout, no connection, a 5xx, a reply that cannot be used),
+ *   Cloud Jev is not asked for {@link BREAKER_OPEN_MS}. The regex decides at
+ *   once, instead of every tool call on the machine waiting out the Cloud
+ *   timeout. Then ONE call goes through (half-open): an answer closes the
+ *   breaker, and another failure opens it again. A 429 is not a failure here,
+ *   because the Cloud transport already honours its Retry-After
+ *   (`cloudRetryAfter` in `jev-client.ts`). Nor is a call this machine
+ *   abandoned itself, or one its own settings stopped.
+ * - **A report** in `errors.json`, machine-level (`id: "jevMode"`, beside
+ *   `jev_unconfigured`):
+ *   - `jev_rate_limited: <n> calls fell back to regex in the last 10 min`,
+ *     while FailproofAI Cloud refuses calls for the organization's Jev rate
+ *     limit;
+ *   - `jev_unavailable: …`, while the breaker is open.
+ *
+ *   Both clear as soon as a call is answered again. The count is refreshed at
+ *   most every {@link REPORT_REFRESH_MS}, so a burst of refusals does not
+ *   become a burst of writes.
+ *
+ * The state is module-level, like the Retry-After cool-down and the throttle:
+ * the daemon's warm worker is the process that sees every call. A one-shot
+ * hook process, on a machine not set up yet, starts clean each time. The state
+ * is keyed by where the calls go (endpoint and machine id), so a reconnect
+ * starts afresh.
+ */
+import { readCloudPolicyErrors, writeCloudPolicyErrors, type CloudPolicyError } from "../cloud-policy-errors";
+import type { JevReview } from "./combine";
+
+/** Consecutive failures that open the breaker. */
+export const BREAKER_FAILURES = 3;
+/** How long an open breaker skips FailproofAI Cloud Jev before it lets one call through. */
+export const BREAKER_OPEN_MS = 60_000;
+/** The window `jev_rate_limited` counts over. */
+export const RATE_LIMIT_WINDOW_MS = 10 * 60_000;
+/** A changing count is re-reported at most this often. */
+export const REPORT_REFRESH_MS = 30_000;
+
+/** Reported while FailproofAI Cloud refuses this machine's calls for the org's Jev rate limit. */
+export const JEV_RATE_LIMITED = "jev_rate_limited";
+/** Reported while the breaker is open. */
+export const JEV_UNAVAILABLE = "jev_unavailable";
+
+/** The fallback reason of a call the open breaker did not send (a known activity code). */
+export const BREAKER_SKIP_REASON = "unavailable";
+
+interface State {
+  scope: string;
+  failures: number;
+  lastFailure: string | null;
+  /** When an open breaker lets its next call through; null = closed. */
+  openUntil: number | null;
+  /** The half-open trial call is in flight: the others still skip. */
+  probing: boolean;
+  /** When each rate-limited fallback happened, within the window. */
+  rateLimited: number[];
+  /** The count last reported, and when, so the report changes at most every REPORT_REFRESH_MS. */
+  reportedRate: { n: number; at: number } | null;
+  /** The entries last merged into `errors.json` by {@link reportCloudJevHealth}. */
+  lastReport: string;
+}
+
+const fresh = (scope: string): State => ({
+  scope,
+  failures: 0,
+  lastFailure: null,
+  openUntil: null,
+  probing: false,
+  rateLimited: [],
+  reportedRate: null,
+  lastReport: "[]",
+});
+
+let state: State = fresh("");
+const clock = (): number => performance.now();
+
+/** Tests only. */
+export function _resetCloudJevHealthForTest(): void {
+  state = fresh("");
+}
+
+function forScope(scope: string): State {
+  if (state.scope !== scope) state = fresh(scope);
+  return state;
+}
+
+/** Whether a call may go to FailproofAI Cloud now; `probe` marks the half-open trial. */
+export type CloudJevGate = { ask: true; probe: boolean } | { ask: false };
+
+/** Ask the breaker before sending a call. Taking the trial (`probe: true`) must be followed by {@link recordCloudJevResult}. */
+export function cloudJevGate(scope: string, at: number = clock()): CloudJevGate {
+  const s = forScope(scope);
+  if (s.openUntil === null) return { ask: true, probe: false };
+  if (at < s.openUntil || s.probing) return { ask: false };
+  s.probing = true;
+  return { ask: true, probe: true };
+}
+
+/** What one Cloud call's review says about Cloud's health. */
+export type CloudJevResult = "answered" | "rate-limited" | "failed" | "neutral";
+
+/** Fallback codes that say FailproofAI Cloud Jev could not be used; `http-5xx` too. */
+const FAILURES: ReadonlySet<string> = new Set(["timeout", "network", "malformed", "model-mismatch", "upstream-error", "error"]);
+
+/**
+ * - `answered`: Jev's verdict arrived.
+ * - `rate-limited`: FailproofAI Cloud refused the call for a rate limit, or its
+ *   Retry-After held the call (`http-429`); or the machine's own request budget
+ *   stopped it (`rate-limited`), which a Cloud 429 empties so the calls right
+ *   behind it do not go out (`jev-throttle.ts`).
+ * - `failed`: timeout, no connection, a 5xx, or a reply that could not be used.
+ * - `neutral`: anything that says nothing about Cloud. That covers a call this
+ *   machine aborted (the regex decided first), its own config, and Cloud
+ *   refusing THIS request (4xx): Cloud answered, so it is up.
+ */
+export function classifyCloudJevReview(
+  review: JevReview,
+  opts: { reachedCloud: boolean } = { reachedCloud: true },
+): CloudJevResult {
+  if (review.kind === "answered") return opts.reachedCloud ? "answered" : "neutral";
+  if (review.kind !== "fallback") return "neutral";
+  const code = review.reason;
+  if (code === "http-429" || code === "rate-limited") return "rate-limited";
+  if (FAILURES.has(code) || /^http-5\d\d$/.test(code)) return "failed";
+  return "neutral";
+}
+
+/** Record one call's result against the breaker and the report. */
+export function recordCloudJevResult(
+  scope: string,
+  result: CloudJevResult,
+  code: string | null,
+  probe: boolean,
+  at: number = clock(),
+): void {
+  if (state.scope !== scope) return; // A call to a connection this machine no longer has.
+  const s = state;
+  if (probe) s.probing = false;
+  switch (result) {
+    case "answered":
+      s.failures = 0;
+      s.lastFailure = null;
+      s.openUntil = null;
+      s.rateLimited = [];
+      break;
+    case "rate-limited":
+      s.rateLimited.push(at);
+      // A 429 is Cloud answering, so it is up: the breaker's streak ends, and
+      // its Retry-After, not the breaker, holds the calls behind this one. The
+      // machine's own budget says nothing about Cloud either way.
+      if (code === "http-429") {
+        s.failures = 0;
+        s.openUntil = null;
+      }
+      break;
+    case "failed":
+      s.failures += 1;
+      s.lastFailure = code;
+      if (probe || s.failures >= BREAKER_FAILURES) s.openUntil = at + BREAKER_OPEN_MS;
+      break;
+    case "neutral":
+      break;
+  }
+}
+
+/** Is `message` one of this module's reports? */
+export function isCloudJevHealthMessage(message: string): boolean {
+  return message.startsWith(JEV_RATE_LIMITED) || message.startsWith(JEV_UNAVAILABLE);
+}
+
+/** The report as it stands: `errors.json` entries, none when all is well. */
+export function cloudJevHealthErrors(at: number = clock()): CloudPolicyError[] {
+  const s = state;
+  const out: CloudPolicyError[] = [];
+  s.rateLimited = s.rateLimited.filter((t) => at - t < RATE_LIMIT_WINDOW_MS);
+  const n = s.rateLimited.length;
+  if (n === 0) {
+    s.reportedRate = null;
+  } else {
+    if (s.reportedRate === null || at - s.reportedRate.at >= REPORT_REFRESH_MS) s.reportedRate = { n, at };
+    const minutes = Math.round(RATE_LIMIT_WINDOW_MS / 60_000);
+    const count = s.reportedRate.n;
+    out.push({
+      id: "jevMode",
+      version: null,
+      kind: "daemon",
+      message: `${JEV_RATE_LIMITED}: ${count} call${count === 1 ? "" : "s"} fell back to regex in the last ${minutes} min`,
+    });
+  }
+  if (s.openUntil !== null) {
+    out.push({
+      id: "jevMode",
+      version: null,
+      kind: "daemon",
+      message:
+        `${JEV_UNAVAILABLE}: FailproofAI Cloud Jev failed ${BREAKER_FAILURES} or more calls in a row ` +
+        `(last: ${s.lastFailure ?? "error"}), so tool calls skip it for ${BREAKER_OPEN_MS / 1000} s at a time ` +
+        "and the regex decides alone",
+    });
+  }
+  return out;
+}
+
+/**
+ * Merge the report into `errors.json` now, when it changed since this process
+ * last merged it, so the daemon's next poll carries it without waiting for the
+ * next hook. Every other entry is kept. Never throws.
+ */
+export function reportCloudJevHealth(at: number = clock()): void {
+  try {
+    const entries = cloudJevHealthErrors(at);
+    const text = JSON.stringify(entries);
+    if (text === state.lastReport) return;
+    state.lastReport = text;
+    const report = (readCloudPolicyErrors() ?? []).filter((e) => !(e.id === "jevMode" && isCloudJevHealthMessage(e.message)));
+    writeCloudPolicyErrors([...report, ...entries]);
+  } catch {
+    // A report must not cost a hook its answer; the next call reports again.
+  }
+}