failproofai 1.0.6 → 1.0.7-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "failproofai",
-  "version": "1.0.6",
+  "version": "1.0.7-beta.1",
   "description": "Observability and enforcement for AI agent harnesses. 39 built-in policies hooked into 12 of them — Claude Code, Codex, Cursor, Hermes, OpenClaw and more — blocking the tool call before it runs. Local dashboard included, no account needed.",
   "bin": {
     "failproofai": "./dist/cli.mjs",
@@ -81,14 +81,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.125.0",
+    "@anthropic-ai/sdk": "^0.127.0",
     "@mdx-js/mdx": "^3.1.1",
     "@tailwindcss/postcss": "^4.3.1",
     "@tanstack/react-virtual": "^3.14.10",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.5",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.1.0",
@@ -122,15 +122,15 @@
     "browserslist": "4.28.8"
   },
   "optionalDependencies": {
-    "@failproofai/failproofaid-linux-x64": "1.0.6",
-    "@failproofai/failproofaid-linux-arm64": "1.0.6",
-    "@failproofai/failproofaid-darwin-x64": "1.0.6",
-    "@failproofai/failproofaid-darwin-arm64": "1.0.6"
+    "@failproofai/failproofaid-linux-x64": "1.0.7-beta.1",
+    "@failproofai/failproofaid-linux-arm64": "1.0.7-beta.1",
+    "@failproofai/failproofaid-darwin-x64": "1.0.7-beta.1",
+    "@failproofai/failproofaid-darwin-arm64": "1.0.7-beta.1"
   },
   "failproofaidBinaries": {
-    "linux-x64": "e075f24a3a0950b631979d9370b665da2c3e2920decfb917ff0831d1f17c9740",
-    "linux-arm64": "b90ce8c642f2685719f4915695615219860daf3155a9c07344cf1e10395028c3",
-    "darwin-x64": "51dd95e9b85226e4f1888c7edaa56ec4464e91eb645d39c5cb7cede16d2da2f1",
-    "darwin-arm64": "f6a1b9d63363e8805e0d72b4fa168fde661bdbbd4125b54047f7de8948ea0f39"
+    "linux-x64": "8fc6dcf94834a332791a76b24c9906ef63371ee91b5a8dc2c764db202d5608a7",
+    "linux-arm64": "ce48b73245adc6a0d7cef2ba74e37693bd00d7cff75a8d27b6bdbd8ba0251613",
+    "darwin-x64": "27d8f9d740d409741d43e75850eea5f956ac6b578628cbf2f364d711f89621a6",
+    "darwin-arm64": "0ee02f87dd6e3f0761b18fd5d60ebbbfd5328f3e99bc3d2c909d41d540ee68a0"
   }
 }

package/pi-extension/index.ts

@@ -404,6 +404,17 @@ export default function failproofaiBridge(pi: PiExtensionApi) {
       session_id: resolveSessionId(e.sessionId, resolveCwd(e.cwd)),
       cwd: resolveCwd(e.cwd),
       hook_event_name: "UserPromptSubmit",
+      // "interactive" | "rpc" | "extension": which channel the input came
+      // through, and the only mark Pi gives about who wrote the prompt. It
+      // names the channel, not the author — `pi -p "<text>"` reports
+      // `interactive` exactly as a person typing does — so the Jev evaluator
+      // uses it only in the direction it is reliable in (`piMachineTurn`,
+      // src/hooks/semantic/intent.ts): `extension`, another extension's
+      // `sendUserMessage()` whose text can be model-written or repo-derived,
+      // is refused, while `interactive`, `rpc` and an absent value are all
+      // recorded as the human's request. Policies read it too, and a later Pi
+      // build may say more here.
+      input_source: e.source,
     });
     if (decision.block) {
       console.error(`[failproofai] prompt blocked: ${decision.reason ?? "blocked by policy"}`);

package/scripts/build-policy-pack.mjs

@@ -31,6 +31,24 @@
  * that stops an agent disabling failproofai, it ships compiled in, and
  * `pack-manifest.ts` REFUSES any pack that declares `alwaysOn`. A pack containing
  * it would be rejected by our own loader — correctly.
+ *
+ * **Every policy states its authority** — whether Jev may clear its verdict —
+ * as the registry would resolve it (`manifestAuthority`), not as a copy of
+ * whatever the catalog happened to spell. A machine running this pack reads
+ * authority from the MANIFEST, so a field left off here is a policy that is
+ * silently hard everywhere it is installed. The entry passes the same fields to
+ * `customPolicies.add`, so a manifest rebuilt from the entry (`failproofai
+ * publish`) says the same thing.
+ *
+ * **It emits no `semantic` array, deliberately.** A pack that declares one
+ * REPLACES this build's compiled-in semantic set wholesale
+ * (`semantic/pack-policies.ts`), and this pack is the dress rehearsal for the
+ * regex floor leaving the package — not for Jev's question set leaving it. So
+ * the 39 builtins travel and the 16 semantic policies stay compiled in, which
+ * also keeps `manifestAuthority` below judging `reviewedBy` against the right
+ * list: the builtin reviewer names, which is what a machine installing this pack
+ * will still be running. The separate `FailproofAI/jev-policies` pack is where
+ * the semantic half ships, and it declares its own `minCliVersion`.
  */
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -40,6 +58,7 @@ import { fileURLToPath } from "node:url";
 // The one place the pack's id is decided. Imported rather than restated — see
 // PACK_ID below for what restating it cost.
 import { CORE_SOURCE } from "../src/hooks/pack-store.ts";
+import { manifestAuthority } from "../src/hooks/policy-authority.ts";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // `--out <dir>` lets the conformance test generate into a temp directory rather
@@ -95,6 +114,9 @@ for (const policy of BUILTIN_POLICIES) {
     defaultEnabled: policy.defaultEnabled === true,
     match: policy.match,
     fn: policy.fn,
+    // Whether Jev may clear it; see the note on authority at the top.
+    ...(policy.authority !== undefined ? { authority: policy.authority } : {}),
+    ...(policy.reviewedBy !== undefined ? { reviewedBy: policy.reviewedBy } : {}),
   });
 }
 `;
@@ -120,7 +142,20 @@ try {
 // validates these with the loader's own rules, so a shape the loader would
 // refuse fails this build rather than shipping.
 const { POLICY_CATALOG } = await import(join(ROOT, "src/hooks/policy-catalog.ts"));
-const policies = POLICY_CATALOG.filter((p) => !p.alwaysOn).map((p) => ({ ...p }));
+const policies = POLICY_CATALOG.filter((p) => !p.alwaysOn).map((p) => {
+  // Throws on a declaration the registry would quietly downgrade: in the
+  // catalog that is a typo or a renamed semantic policy, and publishing it
+  // would turn a reviewed decision into an unannounced hard one. The fields
+  // come from the same call, so the check cannot be skipped without the
+  // manifest losing its authority too.
+  const resolved = manifestAuthority(p);
+  // Spread first so every field keeps its catalog position; only the two
+  // authority fields are replaced by their resolved values.
+  const entry = { ...p, authority: resolved.authority };
+  if (resolved.reviewedBy) entry.reviewedBy = resolved.reviewedBy;
+  else delete entry.reviewedBy;
+  return entry;
+});
 
 const manifest = JSON.stringify(
   { id: PACK_ID, version, effect: "enforce", policies },
@@ -138,8 +173,10 @@ writeFileSync(
 );
 
 const omitted = POLICY_CATALOG.filter((p) => p.alwaysOn).map((p) => p.name);
+const reviewable = policies.filter((p) => p.authority === "reviewable").length;
 console.log(
-  `[policy-pack] ${PACK_ID}@${version} — ${policies.length} policies, ` +
+  `[policy-pack] ${PACK_ID}@${version} — ${policies.length} policies ` +
+  `(${reviewable} reviewable by Jev, ${policies.length - reviewable} hard), ` +
   `${(entryBytes.length / 1024).toFixed(1)} KB entry` +
   (omitted.length ? `; omitted alwaysOn: ${omitted.join(", ")}` : ""),
 );

package/src/hooks/builtin-policies.ts

@@ -2215,17 +2215,29 @@ const READ_LIKE_CMDS =
  * separator characters that appear in compound argv tokens (':' for Docker
  * volume mounts and PATH-like lists, '=' for env var assignments) so that a
  * suffix like '/dashboard.mdx' in 'docs/STAR/dashboard.mdx' or '/docs' in
- * '-v HOST_DIR:/docs' is not misread as a standalone absolute path.
+ * '-v HOST_DIR:/docs' is not misread as a standalone absolute path. '/' is in
+ * that list too, so a match cannot START on the second slash of a protocol
+ * separator: 'http://localhost:3000/x' used to yield '/localhost:3000/x'.
+ * A match that starts on the FIRST slash is untouched, so '//etc/passwd' —
+ * a real, working spelling of /etc/passwd — is still extracted and still
+ * resolves to /etc/passwd.
+ *
+ * Runs of slashes with nothing else ('//', '///') are dropped: those are a
+ * line-comment marker, not a directory. They used to resolve to the filesystem
+ * root, which denied any read-like command carrying a '// …' comment — a
+ * heredoc writing a TypeScript file into the project, say. A lone '/' is the
+ * root and is kept.
  */
 function extractAbsolutePaths(command: string): string[] {
   const paths: string[] = [];
-  const pathRe = /(?<![a-zA-Z0-9_.\-~\\*?:=])(?:~\/[^\s;|&"'()\[\]{}]*|~(?=\s|$|[;|&"'()\[\]{}])|\/[^\s;|&"'()\[\]{}]*)/g;
+  const pathRe = /(?<![a-zA-Z0-9_.\-~\\*?:=/])(?:~\/[^\s;|&"'()\[\]{}]*|~(?=\s|$|[;|&"'()\[\]{}])|\/[^\s;|&"'()\[\]{}]*)/g;
 
   function addPaths(s: string): void {
     pathRe.lastIndex = 0;
     let m: RegExpExecArray | null;
     while ((m = pathRe.exec(s)) !== null) {
       let p = m[0];
+      if (/^\/{2,}$/.test(p)) continue; // a `//` comment marker, not the root
       if (p === "~") p = homedir();
       else if (p.startsWith("~/")) p = join(homedir(), p.slice(2));
       paths.push(p);
@@ -3178,7 +3190,13 @@ export function registerBuiltinPolicies(enabledNames: string[]): void {
     // A guard against the agent disabling failproofai that any of those can
     // switch off is not a guard.
     if (policy.alwaysOn || enabledSet.has(normalizePolicyName(policy.name))) {
-      registerPolicy(policy.name, policy.description, policy.fn, policy.match, 0, policy.params);
+      // `alwaysOn` travels with the declaration so the self-protection guard
+      // resolves to hard even if its catalog entry ever said otherwise.
+      registerPolicy(policy.name, policy.description, policy.fn, policy.match, 0, policy.params, {
+        authority: policy.authority,
+        reviewedBy: policy.reviewedBy,
+        alwaysOn: policy.alwaysOn,
+      });
     }
   }
 }

package/src/hooks/cloud-enrollment-cli.ts

@@ -377,7 +377,7 @@ export function versionStatusLines(): string[] {
   const daemon = recorded?.daemon ?? "not installed";
   return [
     `CLI ${cliVersion} · daemon ${daemon}${skew ? " (STALE)" : ""} · layout ${recorded?.layout ?? "-"}`,
-    ...(skew ? ["  Run `failproofai config` to update the daemon."] : []),
+    ...(skew ? ["  Run `failproofai update` to update the daemon."] : []),
   ];
 }
 

package/src/hooks/cloud-managed-policies.ts

@@ -8,6 +8,8 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 import { cloudPoliciesDir } from "./fp-home";
+import { authorityFieldsOf } from "./policy-authority";
+import type { PolicyAuthority } from "./policy-types";
 
 /**
  * Active-manifest schema versions this reader accepts.
@@ -44,6 +46,19 @@ export interface CloudManagedPolicyArtifact {
   sha256: string;
   path: string;
   deployment: number;
+  /**
+   * Whether Jev may clear this policy's verdict once it is configured, as the
+   * ASSIGNMENT declares it — code inside the artifact cannot grant itself this.
+   * Absent means `hard`, which is what keeps Jev from weakening central
+   * enforcement by default: a cloud policy is only ever reviewable because
+   * whoever deployed it said so. Applies to every hook the artifact registers.
+   *
+   * Read and validated here; the daemon has to carry it into `active.json`
+   * (`ActivePolicy` in `cloud_policies.rs`) before a deployment can set it.
+   */
+  authority?: PolicyAuthority;
+  /** The semantic policies that must all be asked and none answer `deny`; see `authority`. */
+  reviewedBy?: string[];
 }
 
 interface ActiveManifest {
@@ -55,6 +70,8 @@ interface ActiveManifest {
     effect?: string;
     sha256: string;
     path: string;
+    authority?: unknown;
+    reviewedBy?: unknown;
   }>;
 }
 
@@ -206,6 +223,11 @@ export function readActiveCloudManagedPolicies(): CloudManagedPolicyArtifact[] {
       sha256: policy.sha256,
       path,
       deployment: manifest.deployment,
+      // Unlike `effect`, a malformed authority is dropped rather than refused:
+      // dropping it makes this policy `hard`, the default that keeps enforcing,
+      // while refusing would take the whole deployment down over an optional
+      // field. Absent stays absent.
+      ...authorityFieldsOf(policy as unknown as Record<string, unknown>),
     };
   });
 }

package/src/hooks/custom-hooks-loader.ts

@@ -33,6 +33,7 @@ import type { CustomHook, PolicyCatalogEntry } from "./policy-types";
 import type { CloudManagedPolicyArtifact } from "./cloud-managed-policies";
 import type { ResolvedPack } from "./pack-manifest";
 import { customPoliciesDir, shimsDir } from "./fp-home";
+import { warnAuthority, withMergedAuthority } from "./policy-authority";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
 
@@ -448,9 +449,19 @@ export async function loadAllCustomHooks(
       `cloud-managed policies ${existing.id} and ${policy.id} have identical source, so they share ` +
         `one artifact and load as one policy; enforcing it if either asks to enforce`,
     );
-    if (existing.effect !== "enforce" && policy.effect === "enforce") {
-      cloudManagedByPath.set(key, policy);
+    // Authority resolves toward HARD, for the same reason: reviewable only if
+    // every assignment behind these bytes says so. Keeping one record's
+    // declaration let the order of active.json decide, so a team's reviewable
+    // assignment could clear what an org-wide hard one enforces.
+    const winner = existing.effect !== "enforce" && policy.effect === "enforce" ? policy : existing;
+    const { merged, overruled } = withMergedAuthority(winner, [existing, policy]);
+    if (overruled) {
+      warnAuthority(
+        `cloud-managed policies ${existing.id} and ${policy.id} share one artifact and do not all declare it ` +
+          `reviewable, so it stays hard`,
+      );
     }
+    cloudManagedByPath.set(key, merged);
   }
 
   // Installed packs, keyed by artifact path — the same content-addressing, and
@@ -482,14 +493,34 @@ export async function loadAllCustomHooks(
    *
    * Winner precedence on a name both declare, because the merged record carries
    * the winner's id and version and there is no merging two different defaults.
+   *
+   * Except AUTHORITY, which resolves toward hard like the effect resolves toward
+   * enforce (`withMergedAuthority`): a name is reviewable only if every pack
+   * behind the artifact declares it reviewable. A pack whose manifest does not
+   * list the name at all counts as hard — its copy of the artifact registers
+   * the policy all the same, undeclared, and an undeclared pack policy is hard.
+   * Winner precedence here would let one pack's manifest make another pack's
+   * policy reviewable, which is the one thing a manifest may never do.
    */
   const unionCatalog = (
     winner: PolicyCatalogEntry[],
     other: PolicyCatalogEntry[],
-  ): PolicyCatalogEntry[] => [
-    ...winner,
-    ...other.filter((p) => !winner.some((w) => w.name === p.name)),
-  ];
+  ): { policies: PolicyCatalogEntry[]; overruled: string[] } => {
+    /** Names a pack asked to be reviewable and did not get, for the warning. */
+    const overruled: string[] = [];
+    const harden = (entry: PolicyCatalogEntry, peer: PolicyCatalogEntry | undefined) => {
+      const r = withMergedAuthority(entry, [entry, peer ?? {}]);
+      if (r.overruled) overruled.push(entry.name);
+      return r.merged;
+    };
+    return {
+      policies: [
+        ...winner.map((w) => harden(w, other.find((p) => p.name === w.name))),
+        ...other.filter((p) => !winner.some((w) => w.name === p.name)).map((p) => harden(p, undefined)),
+      ],
+      overruled,
+    };
+  };
 
   const packByPath = new Map<string, ResolvedPack>();
   /**
@@ -535,12 +566,19 @@ export async function loadAllCustomHooks(
     // being intersected away.
     const winner = existing.effect !== "enforce" && pack.effect === "enforce" ? pack : existing;
     const other = winner === existing ? pack : existing;
+    const catalog = unionCatalog(winner.policies, other.policies);
     packByPath.set(key, {
       ...winner,
-      policies: unionCatalog(winner.policies, other.policies),
+      policies: catalog.policies,
       enabled: unionSelection(winner.enabled, other.enabled),
       clis: unionSelection(winner.clis, other.clis),
     });
+    if (catalog.overruled.length > 0) {
+      warnAuthority(
+        `packs ${existing.id} and ${pack.id} share one artifact and do not all declare ` +
+          `${catalog.overruled.join(", ")} reviewable, so ${catalog.overruled.length === 1 ? "it stays" : "they stay"} hard`,
+      );
+    }
   }
 
   // 1. Explicit custom policy paths. Accept a string for callers/configs using

package/src/hooks/custom-hooks-registry.ts

@@ -4,9 +4,14 @@
  * from 'failproofai') and the hook handler (which reads from this file) share the
  * same in-process state when running within the same Node.js process.
  */
-import type { CustomHook } from "./policy-types";
+import type { CustomHook, SemanticPolicyDeclaration } from "./policy-types";
 
 const REGISTRY_KEY = "__failproofai_custom_hooks__";
+/**
+ * Beside the hook registry, on the same key namespace and cleared by the same
+ * call — the two are one registration pass and a build step reads both.
+ */
+const SEMANTIC_KEY = "__failproofai_semantic_policies__";
 
 function getRegistry(): CustomHook[] {
   const g = globalThis as Record<string, unknown>;
@@ -14,17 +19,56 @@ function getRegistry(): CustomHook[] {
   return g[REGISTRY_KEY] as CustomHook[];
 }
 
+function getSemanticRegistry(): SemanticPolicyDeclaration[] {
+  const g = globalThis as Record<string, unknown>;
+  if (!Array.isArray(g[SEMANTIC_KEY])) g[SEMANTIC_KEY] = [];
+  return g[SEMANTIC_KEY] as SemanticPolicyDeclaration[];
+}
+
 export const customPolicies = {
   add(hook: CustomHook): void {
     getRegistry().push(hook);
   },
 };
 
+/**
+ * Register a semantic (Jev) policy — a question set for the classifier, read by
+ * `failproofai publish` and emitted as the pack manifest's `semantic` array.
+ *
+ * A SEPARATE namespace from `customPolicies`, deliberately, rather than a
+ * `customPolicies.addSemantic`. A semantic policy has no `fn` and no `match`,
+ * and nothing about it ever executes on a user's machine: what installs is the
+ * declaration in the manifest, and the artifact's call here matters only at
+ * build time. Putting it behind the object whose entries return
+ * `allow()`/`deny()` invites exactly the shape confusion the manifest parser
+ * would then have to catch — a function on a semantic entry, a probe list on a
+ * regex one — and both mistakes would be silent until somebody read a manifest.
+ *
+ * Nothing is validated here. `parsePackSemanticPolicy` in `pack-manifest.ts`
+ * owns every rule, and it is applied at BUILD time (where the author can still
+ * fix it) and again at load time (where the bytes may have come from anywhere).
+ * Validating a third time in the setter would be a third copy of the rules.
+ */
+export const semanticPolicies = {
+  add(policy: SemanticPolicyDeclaration): void {
+    getSemanticRegistry().push(policy);
+  },
+};
+
 export function getCustomHooks(): CustomHook[] {
   return getRegistry();
 }
 
+export function getSemanticRegistrations(): SemanticPolicyDeclaration[] {
+  return getSemanticRegistry();
+}
+
 export function clearCustomHooks(): void {
   const g = globalThis as Record<string, unknown>;
   g[REGISTRY_KEY] = [];
+  // Both maps, on one call. A loader that cleared only the hooks would carry
+  // one entry file's semantic policies into the next file's build — and since
+  // the semantic half is read after the load rather than during it, the extras
+  // would be published under the wrong pack with nothing to notice.
+  g[SEMANTIC_KEY] = [];
 }

package/src/hooks/effective-reviewers.ts

@@ -0,0 +1,79 @@
+/**
+ * The semantic checks a `reviewedBy` may name ON THIS MACHINE.
+ *
+ * ## Why this is not simply `SEMANTIC_REVIEWER_NAMES`
+ *
+ * A pack that declares its own `semantic` entries replaces the compiled-in
+ * `SEMANTIC_POLICIES` wholesale (`semantic/pack-policies.ts`). So on that
+ * machine the sixteen builtin names are checks that will never be asked, and the
+ * pack's own names are the only ones that will — while
+ * `resolvePolicyAuthority`, judging against the builtin set, would read the
+ * pack's `reviewedBy: ["its-own-check"]` as naming a check "this build does not
+ * have" and downgrade the policy to `hard` with nothing but a warning in the
+ * hook log. That is a rewritten policy set arriving with its reviewability
+ * quietly removed: the deny half of the two-tier evaluator working exactly as
+ * documented while the clearing half cannot fire once — the failure
+ * `policy-reviewability.ts` was written to make audible, reintroduced one layer
+ * down.
+ *
+ * The names come from the MANIFEST, which is already where `authority` and
+ * `reviewedBy` themselves are read from, so this adds no new trust and imports
+ * no semantic module.
+ *
+ * ## Why it is a module of its own, and cached the way it is
+ *
+ * `registerPolicy` asks this for every policy that declares an authority — forty
+ * times per hook event — and the honest answer costs a digest verification per
+ * installed pack. So it is cached, and the cache is dropped by `clearPolicies()`:
+ * one read per registration pass, and the answer's lifetime is exactly the
+ * registry's. That is the right coupling rather than a convenient one — this set
+ * describes the policies sitting in the registry, and the handler rebuilds both
+ * together, so they cannot come to describe different machines.
+ *
+ * It lives beside `policy-registry.ts` rather than inside `pack-manifest.ts`
+ * because the registry may not depend on the whole manifest reader: several
+ * tests isolate themselves from the running machine's real packs by mocking
+ * `pack-manifest` down to `readInstalledPacks` and `hasInstalledPacks`, and a
+ * registration path reaching for a third export of that module breaks them all
+ * — loudly here, but it is the shape of a change that would later break them
+ * silently.
+ */
+import { readInstalledPacks } from "./pack-manifest";
+import { SEMANTIC_REVIEWER_NAMES } from "./policy-authority";
+
+let cached: ReadonlySet<string> | null = null;
+
+/**
+ * The installed packs' semantic policy names when any pack declares some, and
+ * this build's compiled-in set otherwise.
+ *
+ * Never throws: an unreadable manifest declares nothing, and the builtin set
+ * stands. That is the same fail-open posture every other reader of the pack
+ * manifest takes, and here it also fails in the safe direction — a pack's
+ * `reviewedBy` will not match a builtin name, so its policies stay `hard`
+ * rather than being cleared by a question nobody could read.
+ */
+export function effectiveReviewerNames(): ReadonlySet<string> {
+  if (cached) return cached;
+  let names: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES;
+  try {
+    const declared = readInstalledPacks().packs.flatMap((p) => (p.semantic ?? []).map((s) => s.name));
+    // Only when a pack actually declared some. A machine whose packs carry only
+    // the regex floor still runs the compiled-in semantic set, so its builtin
+    // reviewer names are the live ones.
+    if (declared.length > 0) names = new Set(declared);
+  } catch {
+    // See above: silence here is the builtin set, not an empty one.
+  }
+  cached = names;
+  return names;
+}
+
+/**
+ * Drop the cached answer. Called by `clearPolicies()`, which every evaluation
+ * runs before it registers anything — so a pack installed under a long-lived
+ * warm worker is picked up on the next event rather than at the next restart.
+ */
+export function forgetEffectiveReviewerNames(): void {
+  cached = null;
+}

package/src/hooks/first-run-gate.ts

@@ -35,6 +35,11 @@ export const FIRST_RUN_EXEMPT_SUBCOMMANDS: readonly string[] = [
   // Same reason: a backfill is an explicit instruction about an already-set-up
   // machine, and interrupting it to offer setup answers a question nobody asked.
   "backfill",
+  // `jev setup` is configuration in its own right, and `jev status` / `test` /
+  // `remove` inspect or undo it. It is also the command most likely to be
+  // scripted with a key on stdin — a wizard in front of it would read that key
+  // as the answer to its first question.
+  "jev",
 ];
 
 export function shouldOfferFirstRun(args: readonly string[]): boolean {

package/src/hooks/fp-home.ts

@@ -51,6 +51,7 @@
  *   VERSION                  layout / cli / daemon versions
  *   config.json       0644   non-secret: mode, daemon, collector prefs
  *   credentials.json  0600   every token
+ *   jev.json          0600   the customer's own Jev endpoint + key (BYOK opt-in)
  *   policies-config.json     the builtin enable/disable set + params
  *   bin/                     downloaded daemon binaries, one per version
  *   policies/                every policy: the user's *.mjs sit directly here
@@ -148,6 +149,14 @@ export const configFile = (home?: string) => atHome(home, "config.json");
  */
 export const credentialsFile = (home?: string) => atHome(home, "credentials.json");
 
+/**
+ * The customer's own Jev endpoint and key (BYOK), owner-only. Its presence is
+ * the whole opt-in to the two-tier evaluator: absent, hooks run the regex
+ * engine exactly as before. GLOBAL only — a repository can never set it. See
+ * `src/hooks/semantic/jev-config.ts`.
+ */
+export const jevConfigFile = (home?: string) => atHome(home, "jev.json");
+
 // ── Daemon binaries ──────────────────────────────────────────────────────────
 
 export const binDir = (home?: string) => atHome(home, "bin");
@@ -389,6 +398,12 @@ export const failedDir = (home?: string) => resolve(stateDir(home), "failed");
 export const collectorHealthFile = (home?: string) => resolve(stateDir(home), "collector-health.json");
 /** Per-session enforcement pauses, keyed by a hash of the session id. */
 export const sessionPauseDir = () => resolve(stateDir(), "sessions");
+/**
+ * The semantic (Jev) evaluator's local state: `sessions/<id>.json` holds the
+ * human prompts recorded at `UserPromptSubmit`, and `verdicts.jsonl` one row
+ * per semantic evaluation. Written only when a Jev config (BYOK) is present.
+ */
+export const semanticDir = () => resolve(stateDir(), "semantic");
 /**
  * When the scheduled audit last ran, and when the next one is due.
  *
@@ -554,6 +569,9 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // policy silently — it keeps enforcing whatever it last had, reports healthy,
   // and never reconciles again. Nothing re-derives a token.
   { path: credentialsFile, class: "user-typed" },
+  // The Jev BYOK config. A person typed the key; nothing regenerates it, and
+  // losing it silently turns the two-tier evaluator off.
+  { path: jevConfigFile, class: "user-typed" },
   // Holds `daemon.configured` (the flag that makes the machine fail closed),
   // the collector preferences, `[audit] auto`, the telemetry opt-out, and
   // `collector.sources.*.extra_paths` — the entire output of `harness add-path`.
@@ -642,6 +660,11 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   { path: codexSessionPathsFile, class: "derived" },
   { path: shimsDir, class: "derived" },
   { path: sessionPauseDir, class: "derived" },
+  // Recorded prompts (a six-hour window that only ever lets Jev clear a
+  // reviewable policy) and a local diagnostic log of semantic verdicts that is
+  // never shipped. Losing either costs a clear and some history, never
+  // enforcement.
+  { path: semanticDir, class: "derived" },
   { path: logsDir, class: "derived" },
   { path: lastVersionFile, class: "derived" },
   { path: launcherMarker, class: "derived" },