failproofai 1.0.8 → 1.0.9-beta.1

package/src/hooks/policy-reviewability.ts

@@ -61,8 +61,8 @@ import { resolve } from "node:path";
 import { discoverPolicyFiles } from "./custom-hooks-loader";
 import { customPoliciesDir } from "./fp-home";
 import { configuredCustomPolicyPaths, findProjectConfigDir, readMergedHooksConfig } from "./hooks-config";
-import { hasInstalledPacks, readInstalledPacks } from "./pack-manifest";
-import { resolvePolicyAuthority, SEMANTIC_REVIEWER_NAMES } from "./policy-authority";
+import { hasInstalledRegexPacks, readInstalledPacks } from "./pack-manifest";
+import { resolvePolicyAuthority } from "./policy-authority";
 import { POLICY_CATALOG } from "./policy-catalog";
 import { normalizePolicyName } from "./policy-registry";
 import type { HooksConfig } from "./policy-types";
@@ -87,11 +87,23 @@ export interface ReviewableCoverage {
    * user convention files — whose policies are not in the counts above.
    */
   customFiles: number;
+  /**
+   * Jev checks the installed packs give it to ask. Zero on a machine with no
+   * pack declaring any — the vanilla install — and then Jev is never called.
+   */
+  jevChecks: number;
 }
 
 /** The command that replaces a pack with one built by this release. */
 export const RETAKE_PACK_COMMAND = "failproofai policies add FailproofAI/policies";
 
+/** The command that gives Jev its checks. The package ships none. */
+export const JEV_POLICIES_ADD_COMMAND = "failproofai policies add FailproofAI/jev-policies";
+
+/** Said wherever Jev is configured but has nothing to ask. Kept short: it is a status line. */
+export const NO_JEV_CHECKS_PROBLEM =
+  `Jev has no checks installed, so it asks nothing and clears nothing. To enable it: \`${JEV_POLICIES_ADD_COMMAND}\`.`;
+
 /**
  * Count a policy set by the authority it would REGISTER with —
  * `resolvePolicyAuthority`, the rule `registerPolicy` applies — so this cannot
@@ -112,11 +124,9 @@ export const RETAKE_PACK_COMMAND = "failproofai policies add FailproofAI/policie
 export function countReviewable(
   policies: Iterable<AuthorityRecord>,
   /**
-   * The semantic checks that can be asked on this machine. Defaults to the
-   * compiled-in set; `surveyReviewableCoverage` passes the pack's when one
-   * declares its own, because otherwise this diagnostic reports "0 of 11
-   * reviewable" on exactly the machines the feature was built for — the ones
-   * running a pack that carries both tiers.
+   * The semantic checks that can be asked on this machine — the ones installed
+   * packs declare. Defaults to none, which is what a machine with no such pack
+   * has: nothing is reviewable there.
    */
   knownReviewers?: ReadonlySet<string>,
 ): {
@@ -157,7 +167,9 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
    */
   let reviewers: ReadonlySet<string> | undefined;
   try {
-    packsInstalled = hasInstalledPacks();
+    // Only a pack with regex policies retires the shim, exactly as handler.ts
+    // decides it: a Jev-only pack (FailproofAI/jev-policies) replaces none.
+    packsInstalled = hasInstalledRegexPacks();
     const packs = readInstalledPacks().packs;
     for (const pack of packs) {
       const selected = pack.enabled;
@@ -169,10 +181,11 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
     // hook path's manifest-only `reviewerNamesFor` cannot see. Anything else and
     // the panel and `jev status` promise a clear that cannot happen.
     const asked = semanticPoliciesFromPacks(jevPacks(packs));
-    reviewers = asked.fromPack ? new Set(asked.policies.map((p) => p.name)) : SEMANTIC_REVIEWER_NAMES;
+    reviewers = new Set(asked.policies.map((p) => p.name));
   } catch {
-    // An unreadable manifest enforces nothing; `readInstalledPacks` already
-    // reports that to the hook log on the path that cares.
+    // An unreadable manifest enforces nothing and gives Jev nothing to ask;
+    // `readInstalledPacks` already reports that to the hook log on the path
+    // that cares.
   }
 
   let config: HooksConfig;
@@ -212,7 +225,7 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
     customFiles = 0;
   }
 
-  return { ...countReviewable(records, reviewers), customFiles };
+  return { ...countReviewable(records, reviewers), customFiles, jevChecks: reviewers?.size ?? 0 };
 }
 
 /**
@@ -244,8 +257,13 @@ export function reviewableSummary(coverage: ReviewableCoverage): string {
  * Nothing is diagnosed for an empty policy set: there is no clear to lose, and
  * an authority warning to someone who enforces nothing answers a question they
  * did not ask.
+ *
+ * Except the one thing that comes first: no installed pack gives Jev any checks.
+ * Then Jev asks nothing whatever the policy set is, and the fix is to install
+ * them, not to re-mark anything.
  */
 export function reviewableProblem(coverage: ReviewableCoverage): string | null {
+  if (coverage.jevChecks === 0) return NO_JEV_CHECKS_PROBLEM;
   // Policies from the user's own files were not counted and may be reviewable,
   // so "never" cannot be said honestly; the summary already says what was skipped.
   if (coverage.enabled === 0 || coverage.reviewable > 0 || coverage.customFiles > 0) return null;

package/src/hooks/policy-types.ts

@@ -46,9 +46,9 @@ export interface RegisteredPolicy {
   /** Whether Jev may clear this policy's deny/instruct; see {@link effectiveAuthority}. */
   authority?: PolicyAuthority;
   /**
-   * The semantic policies (`src/hooks/semantic/policies.ts`) that must all be
-   * asked, and each clear (see {@link PolicyAuthority}), before Jev clears this
-   * policy.
+   * The Jev checks (declared by an installed pack — the package ships none)
+   * that must all be asked, and each clear (see {@link PolicyAuthority}),
+   * before Jev clears this policy.
    */
   reviewedBy?: string[];
 }
@@ -188,7 +188,7 @@ export interface SemanticProbeDeclaration {
 /**
  * A semantic (Jev) policy as its author DECLARES it — a question set, not code.
  *
- * The compiled-in equivalent is `SemanticPolicy` in `semantic/types.ts`, and
+ * The runtime form is `SemanticPolicy` in `semantic/types.ts`, and
  * the one difference is the whole reason both exist: there, `precondition` is a
  * function over the computed facts; here it is the NAME of one, because a
  * declaration has to survive a trip through a JSON manifest and because a

package/src/hooks/safe-config-write.ts

@@ -0,0 +1,119 @@
+/**
+ * Crash-safe writes for configuration files that belong to someone else.
+ *
+ * Every agent integration edits a file the user's agent reads on startup:
+ * `~/.claude/settings.json`, `~/.hermes/config.yaml`, `~/.openclaw/openclaw.json`
+ * and the rest. A plain `writeFileSync` truncates that file first and fills it
+ * second, so a crash, a full disk or a killed process in between leaves the agent
+ * with a half-written config — for Hermes that is a gateway that will not start.
+ * And a later install then refuses to touch the file because it no longer parses,
+ * so nothing repairs it.
+ *
+ * So the new content never goes near the live file until it is complete and on
+ * disk:
+ *
+ *   1. write it to a uniquely named temporary file in the SAME directory (a
+ *      rename is only atomic within one filesystem),
+ *   2. fsync that file,
+ *   3. copy the current file to `<name>.failproofai-backup` — the last version
+ *      before failproofai changed it, for a person to restore by hand,
+ *   4. rename the temporary file over the live one (atomic on POSIX, and a
+ *      replacing move on Windows), then fsync the directory so the rename
+ *      itself survives a power cut.
+ *
+ * Any failure before step 4 leaves the live file exactly as it was and removes
+ * the temporary file. The file keeps its permission bits (Hermes keeps
+ * `config.yaml` at 0600), and a config that is a symlink — a dotfiles checkout —
+ * is written through to its target rather than replaced by a regular file.
+ */
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
+import { basename, dirname, join } from "node:path";
+
+/** Where the copy of the previous version is kept, beside the file itself. */
+export function configBackupPath(path: string): string {
+  return `${resolveWriteTarget(path)}.failproofai-backup`;
+}
+
+/** Hooks for tests to simulate an interruption at the one step that matters. */
+export interface AtomicWriteDeps {
+  rename?: (from: string, to: string) => void;
+}
+
+/** A symlinked config is written through to what it points at. */
+function resolveWriteTarget(path: string): string {
+  try {
+    if (lstatSync(path).isSymbolicLink()) return realpathSync(path);
+  } catch {
+    // Absent or unreadable: write to the path as given.
+  }
+  return path;
+}
+
+export function writeConfigFileAtomic(path: string, content: string, deps: AtomicWriteDeps = {}): void {
+  const target = resolveWriteTarget(path);
+  const dir = dirname(target);
+  mkdirSync(dir, { recursive: true });
+
+  let mode: number | undefined;
+  try {
+    mode = statSync(target).mode & 0o777;
+  } catch {
+    mode = undefined; // a new file: the process umask decides, as writeFileSync would
+  }
+
+  const temporary = join(dir, `.${basename(target)}.failproofai-${process.pid}-${randomBytes(4).toString("hex")}.tmp`);
+  let fd: number | undefined;
+  try {
+    fd = openSync(temporary, "wx", mode ?? 0o666);
+    const bytes = Buffer.from(content, "utf8");
+    let written = 0;
+    while (written < bytes.length) written += writeSync(fd, bytes, written, bytes.length - written);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    // `open` applies the umask; the live file's own bits are what should survive.
+    if (mode !== undefined) chmodSync(temporary, mode);
+
+    if (existsSync(target)) copyFileSync(target, `${target}.failproofai-backup`);
+
+    (deps.rename ?? renameSync)(temporary, target);
+  } catch (err) {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // already closed or never opened
+      }
+    }
+    rmSync(temporary, { force: true });
+    throw err;
+  }
+
+  // Make the rename itself durable. Not supported on every platform (Windows
+  // cannot open a directory); the file content is already safe either way.
+  try {
+    const dirFd = openSync(dir, "r");
+    try {
+      fsyncSync(dirFd);
+    } finally {
+      closeSync(dirFd);
+    }
+  } catch {
+    // best effort
+  }
+}

package/src/hooks/semantic/combine.ts

@@ -22,7 +22,7 @@
  * | Jev answered                                  | reviewable denies/instructs Jev covered are cleared; final =|
  * |                                               | the most severe of {remaining regex results, Jev's verdict} |
  *
- * `shadow` mode computes and records all of it, and still returns the regex
+ * `observe` mode computes and records all of it, and still returns the regex
  * result.
  *
  * ## Where this departs from plan §4
@@ -232,14 +232,14 @@ import type { PolicyAuthority } from "../policy-types";
 // The only value imports, and deliberately from the activity vocabulary rather
 // than local literals: the fallback reason this module writes itself has to
 // be a code the activity store's closed list names, or it is stored and
-// shipped as `other`, and a shadow verdict's model id has to pass the same
+// shipped as `other`, and an observe-mode verdict's model id has to pass the same
 // shape check the row's own `jevModel` does. Importing them makes a rename a
 // compile error here. `jev-activity.ts` is pure (no node imports, no semantic
 // modules), so this costs the hook path nothing.
 import { JEV_MODEL_RE, JEV_REASON_REQUEST_CUT } from "../jev-activity";
 
 export type Decision = "allow" | "deny" | "instruct";
-export type JevMode = "shadow" | "enforce";
+export type JevMode = "observe" | "enforce";
 
 /** One regex policy's verdict, in evaluation order. */
 export interface RegexVerdict {
@@ -383,13 +383,13 @@ export interface JevActivityFields {
 }
 
 /**
- * Jev's own deny or instruct in SHADOW mode — the verdict enforce mode would
+ * Jev's own deny or instruct in OBSERVE mode — the verdict enforce mode would
  * have applied, recorded rather than applied. The handler files it in the
  * activity row's `observed` list, the "would have" record observe-mode cloud
  * and pack policies already use, so FailproofAI Cloud's policy page counts it
  * with no change on its side.
  */
-export interface ShadowVerdict {
+export interface ObserveVerdict {
   /** `semantic/<check>` — the name enforce mode would have attributed it to. */
   policyName: string;
   decision: "deny" | "instruct";
@@ -401,7 +401,7 @@ export interface ShadowVerdict {
 
 export interface CombineOutcome {
   final: FinalVerdict;
-  /** Reviewable regex policies Jev cleared (in shadow: would have cleared). */
+  /** Reviewable regex policies Jev cleared (in observe mode: would have cleared). */
   cleared: string[];
   /**
    * True when the first entry of `final` came from THIS TIER rather than from
@@ -414,11 +414,11 @@ export interface CombineOutcome {
   decidedByJev: boolean;
   activity: JevActivityFields;
   /**
-   * Shadow mode only, and only when Jev's own verdict was deny or instruct.
+   * Observe mode only, and only when Jev's own verdict was deny or instruct.
    * Absent otherwise — including every enforce outcome, where the verdict was
    * APPLIED and `decidedByJev` / the final entries already say so.
    */
-  shadowVerdict?: ShadowVerdict;
+  observeVerdict?: ObserveVerdict;
 }
 
 /**
@@ -495,7 +495,7 @@ export function combineTwoTier(
   const notDenied = new Set(review.notDenied);
   const cleared = wholePicture && !review.unclearableWarned ? verdicts.filter((v) => clears(v, asked, notDenied)).map((v) => v.policyName) : [];
 
-  // Built once, for both modes: enforce applies it, shadow records it, and the
+  // Built once, for both modes: enforce applies it, observe records it, and the
   // two must never disagree about what the verdict WAS.
   const jevEntry = { policyName: review.policyName, reason: review.reason ?? `Flagged by semantic review (${review.policyName})` };
   const enforced = resolveEnforce(verdicts, cleared, review.decision, jevEntry);
@@ -510,7 +510,7 @@ export function combineTwoTier(
     evaluator: review.requestCut ? "jev-fallback" : "jev",
     ...(review.requestCut ? { jevFallbackReason: JEV_REASON_REQUEST_CUT } : {}),
     jevDecision: review.decision,
-    // Only a clear that SOFTENED the call (in shadow: would have). One that
+    // Only a clear that SOFTENED the call (in observe mode: would have). One that
     // Jev's own deny, or another regex deny, still decided over changed
     // nothing — and `jev status` and the policy page's "Cleared by Jev" both
     // read `jevCleared` as calls Jev let through.
@@ -520,11 +520,11 @@ export function combineTwoTier(
     jevMode: mode,
   };
 
-  if (mode === "shadow") {
+  if (mode === "observe") {
     // Jev's own deny or instruct, exactly as enforce mode would have applied it
     // (upward only: a cut or injected call keeps it, as the enforce branch
     // below does). A clear is recorded in `jevCleared`, not here.
-    const shadowVerdict: ShadowVerdict | undefined =
+    const observeVerdict: ObserveVerdict | undefined =
       review.decision === "deny" || review.decision === "instruct"
         ? {
             policyName: jevEntry.policyName,
@@ -535,7 +535,7 @@ export function combineTwoTier(
             version: review.model && JEV_MODEL_RE.test(review.model) ? review.model : "jev",
           }
         : undefined;
-    return { final: legacy, cleared, decidedByJev: false, activity, ...(shadowVerdict ? { shadowVerdict } : {}) };
+    return { final: legacy, cleared, decidedByJev: false, activity, ...(observeVerdict ? { observeVerdict } : {}) };
   }
 
   return { ...enforced, cleared, activity };

package/src/hooks/semantic/evaluator.ts

@@ -98,7 +98,7 @@ export interface SemanticOptions {
    */
   signal?: AbortSignal;
   model?: string;
-  /** Overrides the resolved set (an installed pack's, else the compiled-in one). */
+  /** Overrides the resolved set (the installed packs' checks; empty with none). */
   policies?: ReadonlyArray<SemanticPolicy>;
   /** The agent the call is for: a pack scoped to other agents contributes no checks. */
   cli?: string;
@@ -306,8 +306,8 @@ export function prepareSemantic(input: SemanticInput, opts: SemanticOptions = {}
     scanned,
     input.projectRoot ?? null,
   );
-  // The set an installed pack declared, or the compiled-in one when no pack
-  // declares any — see `pack-policies.ts` for the replacement rule. Resolved
+  // The checks the installed packs declare — none when no pack declares any,
+  // and then nothing is asked (see `pack-policies.ts`). Resolved
   // here rather than by the caller because this is the one place the policy set
   // is read, and a second resolution site is a second answer to "what does this
   // machine ask Jev". A caller that supplies `policies` (a replay, an ablation,
@@ -496,7 +496,7 @@ export interface VerdictLogMeta {
   eventType: string;
   /**
    * What the handler did with the outcome: combined it with the regex results
-   * (`two-tier`), logged it while enforcing the regex result (`shadow`), or
+   * (`two-tier`), logged it while enforcing the regex result (`observe`), or
    * kept the regex result because Jev never answered (`legacy-fallback`).
    *
    * A TRUNCATED call is `two-tier`, not `legacy-fallback`: its clears were
@@ -504,7 +504,7 @@ export interface VerdictLogMeta {
    * `combine.ts`). `truncated` on the same row is what says the clearing half
    * was off for it; the activity row records `jev-fallback` / `truncated`.
    */
-  applied: "two-tier" | "shadow" | "legacy-fallback";
+  applied: "two-tier" | "observe" | "legacy-fallback";
 }
 
 export function verdictLogRow(input: SemanticInput, outcome: SemanticOutcome, meta: VerdictLogMeta): Record<string, unknown> {

package/src/hooks/semantic/jev-client.ts

@@ -469,7 +469,7 @@ async function postJson(url: string, bearer: string, body: unknown, signal: Abor
       body: JSON.stringify(body),
       signal,
       // Never followed. The configured URL is the one `validateBaseUrl` checked
-      // (https, or loopback http in shadow mode only); a redirect would hand the
+      // (https, or loopback http in observe mode only); a redirect would hand the
       // answer — the thing that can clear a deny — to an origin nobody checked,
       // plain http included. No provider redirects this POST.
       redirect: "manual",

package/src/hooks/semantic/jev-config.ts

@@ -55,7 +55,7 @@
  * The one provider whose key is NOT in this file. `failproofai config --token`
  * with a key carrying `jev:evaluate` stores that key in the `jev` slot of
  * `credentials.json` and, when there is no `jev.json` yet, writes one naming
- * this provider, the Cloud origin + `/enforcement/v1/jev` and `mode: "shadow"`.
+ * this provider, the Cloud origin + `/enforcement/v1/jev` and `mode: "observe"`.
  * So for this provider:
  *
  * - the key comes from `credentials.json` (`readJevCloudCredential`), read with
@@ -80,7 +80,7 @@
  *
  * # `mode: "off"`
  *
- * Every provider accepts `off | shadow | enforce`. `off` keeps the file — the
+ * Every provider accepts `off | observe | enforce`. `off` keeps the file — the
  * endpoint, and for BYOK the key — while Jev does not run at all:
  * `loadJevConfig` returns null exactly as for an absent file. It exists so the
  * dashboard can switch the Cloud route off without deleting the file that
@@ -96,8 +96,16 @@ export type { JevCloudCredential } from "../fp-config";
 
 export type JevProviderKind = "typesafe" | "openrouter" | "vercel" | "cloudflare" | "custom" | "failproofai";
 
-/** `off` does not run Jev at all; `shadow` logs Jev and enforces regex; `enforce` applies the combine rules. */
-export type JevConfigMode = "off" | "shadow" | "enforce";
+/** `off` does not run Jev at all; `observe` logs Jev and enforces regex; `enforce` applies the combine rules. */
+export type JevConfigMode = "off" | "observe" | "enforce";
+
+/**
+ * A mode as read from a file, a flag or a request: `off`, `observe` or
+ * `enforce`. Null for anything else.
+ */
+export function parseJevMode(raw: unknown): JevConfigMode | null {
+  return raw === "off" || raw === "observe" || raw === "enforce" ? raw : null;
+}
 
 export interface JevConfig {
   provider: JevProviderKind;
@@ -130,7 +138,7 @@ export interface JevConfig {
   credentialOrigin?: string;
 }
 
-export const DEFAULT_JEV_MODE: "shadow" | "enforce" = "enforce";
+export const DEFAULT_JEV_MODE: "observe" | "enforce" = "enforce";
 
 export const JEV_PROVIDER_KINDS: readonly JevProviderKind[] = ["typesafe", "openrouter", "vercel", "cloudflare", "custom", "failproofai"];
 
@@ -311,7 +319,7 @@ function credentialQueryProblem(url: URL): string | null {
  * No credentials in the URL — not as userinfo, not as a query parameter — and no
  * fragment, because a key belongs in the key field, where it is sent as a bearer
  * and never printed. `validateJevConfig` further accepts the loopback http form
- * only in shadow mode.
+ * only in observe mode.
  */
 export function validateBaseUrl(raw: unknown): ValidationResult<string> {
   if (typeof raw !== "string" || raw.trim() === "") return { ok: false, problem: "baseUrl must be a non-empty string" };
@@ -667,25 +675,26 @@ export function validateJevConfig(
   }
 
   if (o.mode !== undefined) {
-    if (o.mode !== "off" && o.mode !== "shadow" && o.mode !== "enforce") return { ok: false, problem: 'mode must be "off", "shadow" or "enforce"' };
-    cfg.mode = o.mode;
+    const mode = parseJevMode(o.mode);
+    if (mode === null) return { ok: false, problem: 'mode must be "off", "observe" or "enforce"' };
+    cfg.mode = mode;
   }
 
   // Plain http reaches only a loopback host (`validateBaseUrl`), and nothing
   // authenticates the server there: while the local proxy is down, any process
   // of this user — the agent being judged included — can bind its port and
   // answer "none" to every question. In enforce mode that answer clears
-  // reviewable denies; in shadow mode it changes nothing, and `off` sends
+  // reviewable denies; in observe mode it changes nothing, and `off` sends
   // nothing at all, so enforce is the one mode it is refused in.
   if (cfg.baseUrl !== undefined && isPlainHttp(cfg.baseUrl) && cfg.mode === "enforce") {
     return {
       ok: false,
       problem:
-        "plain http (to localhost) is accepted only with mode shadow: in enforce mode Jev's answers can clear a deny, " +
+        "plain http (to localhost) is accepted only with mode observe: in enforce mode Jev's answers can clear a deny, " +
         "and while the local proxy is down any process on this machine could take its port and answer. " +
         (cfg.provider === JEV_CLOUD_PROVIDER
-          ? "Reconnect to an https FailproofAI Cloud URL (failproofai config --token <key> --url https://…), or keep mode shadow"
-          : "Use https, or mode shadow"),
+          ? "Reconnect to an https FailproofAI Cloud URL (failproofai config --token <key> --url https://…), or keep mode observe"
+          : "Use https, or mode observe"),
     };
   }
 

package/src/hooks/semantic/jev-review.ts

@@ -114,7 +114,7 @@ function servedFromCache(response: unknown): boolean {
  * `jev.json`, and the request alone does not say who answered it: two
  * providers asked for the same model build byte-identical requests. Unscoped,
  * an answer one config got — from a plain-http loopback proxy T1 allows only in
- * shadow mode, say — would clear denies under the next config in enforce mode
+ * observe mode, say — would clear denies under the next config in enforce mode
  * without that provider ever being asked. The scope is only hashed into the
  * cache key, never stored, so a URL carrying a credential is safe here.
  */
@@ -152,7 +152,7 @@ export interface JevCallContext {
 }
 
 export function resolveMode(cfg: JevConfig): JevMode {
-  return cfg.mode === "shadow" || cfg.mode === "enforce" ? cfg.mode : DEFAULT_JEV_MODE;
+  return cfg.mode === "observe" || cfg.mode === "enforce" ? cfg.mode : DEFAULT_JEV_MODE;
 }
 
 /**
@@ -359,7 +359,7 @@ export function startJevReview(cfg: JevConfig, call: JevCallContext): TwoTierRev
           sessionId: call.sessionId,
           cli: call.cli,
           eventType: call.eventType,
-          applied: abandoned || review.kind !== "answered" ? "legacy-fallback" : mode === "shadow" ? "shadow" : "two-tier",
+          applied: abandoned || review.kind !== "answered" ? "legacy-fallback" : mode === "observe" ? "observe" : "two-tier",
         });
         appendVerdictLog(hit ? { ...row, cached: true } : row);
       }

package/src/hooks/semantic/jev-stats.ts

@@ -31,9 +31,9 @@ export interface JevStats {
   latencyP95Ms: number | null;
   /**
    * Reviewable policies Jev cleared, by name — enforce mode only, where a
-   * clear changed the outcome. Shadow mode's would-be clears are in
-   * {@link JevStats.shadowClearsByPolicy}, so a renderer that prints only this
-   * field says "nothing cleared" on a shadow-mode machine: print both.
+   * clear changed the outcome. Observe mode's would-be clears are in
+   * {@link JevStats.observeClearsByPolicy}, so a renderer that prints only this
+   * field says "nothing cleared" on an observe-mode machine: print both.
    */
   clearsByPolicy: Record<string, number>;
   // The fields below are optional in the TYPE only so that a caller written
@@ -62,9 +62,9 @@ export interface JevStats {
    */
   decisions?: { allow: number; instruct: number; deny: number };
   /** Consulted calls (`total`) per rollout mode; a row written without a mode is counted in neither. */
-  modes?: { shadow: number; enforce: number };
-  /** What Jev would have cleared in shadow mode, where the regex result was enforced instead. */
-  shadowClearsByPolicy?: Record<string, number>;
+  modes?: { observe: number; enforce: number };
+  /** What Jev would have cleared in observe mode, where the regex result was enforced instead. */
+  observeClearsByPolicy?: Record<string, number>;
   /** Model ids that answered, by count. */
   models?: Record<string, number>;
 }
@@ -160,14 +160,14 @@ export function computeJevStats(
     notConsulted: 0,
     noRequest: 0,
     decisions: { allow: 0, instruct: 0, deny: 0 },
-    modes: { shadow: 0, enforce: 0 },
-    shadowClearsByPolicy: {},
+    modes: { observe: 0, enforce: 0 },
+    observeClearsByPolicy: {},
     models: {},
   };
   const latencies: number[] = [];
   const fallbackReasons = new Counter();
   const clearsByPolicy = new Counter();
-  const shadowClearsByPolicy = new Counter();
+  const observeClearsByPolicy = new Counter();
   const models = new Counter();
 
   for (const raw of entries) {
@@ -197,13 +197,13 @@ export function computeJevStats(
     if (e.jevDecision) stats.decisions[e.jevDecision] += 1;
     if (e.jevLatencyMs !== undefined) latencies.push(e.jevLatencyMs);
     if (e.jevModel) models.bump(e.jevModel);
-    const clears = e.jevMode === "shadow" ? shadowClearsByPolicy : clearsByPolicy;
+    const clears = e.jevMode === "observe" ? observeClearsByPolicy : clearsByPolicy;
     for (const name of e.jevCleared ?? []) clears.bump(name);
   }
 
   stats.fallbackReasons = fallbackReasons.toRecord();
   stats.clearsByPolicy = clearsByPolicy.toRecord();
-  stats.shadowClearsByPolicy = shadowClearsByPolicy.toRecord();
+  stats.observeClearsByPolicy = observeClearsByPolicy.toRecord();
   stats.models = models.toRecord();
   stats.fallbackRate = stats.total > 0 ? stats.fallbacks / stats.total : 0;
   latencies.sort((a, b) => a - b);
@@ -217,8 +217,8 @@ export function computeJevStats(
  * {@link clampJevStatsWindow}), read from the hook activity store. Never
  * throws: an unreadable store reads as no activity.
  *
- * A renderer must show {@link JevStats.shadowClearsByPolicy} as well as
- * `clearsByPolicy`: in shadow mode every clear Jev would have made is in the
+ * A renderer must show {@link JevStats.observeClearsByPolicy} as well as
+ * `clearsByPolicy`: in observe mode every clear Jev would have made is in the
  * former, and the latter is empty. {@link formatJevStats} prints both.
  */
 export async function jevStats(opts: { windowMs?: number; now?: number } = {}): Promise<JevStatsDetail> {
@@ -279,11 +279,11 @@ export function formatJevStats(s: JevStats): string {
   lines.push(...notAsked);
   if (s.latencyP50Ms !== null) lines.push(`  Latency:      p50 ${s.latencyP50Ms} ms, p95 ${s.latencyP95Ms} ms`);
   if (Object.keys(s.clearsByPolicy).length > 0) lines.push(`  Cleared:      ${topCounts(s.clearsByPolicy)}`);
-  if (s.shadowClearsByPolicy && Object.keys(s.shadowClearsByPolicy).length > 0) {
-    lines.push(`  Would clear:  ${topCounts(s.shadowClearsByPolicy)} (shadow mode)`);
+  if (s.observeClearsByPolicy && Object.keys(s.observeClearsByPolicy).length > 0) {
+    lines.push(`  Would clear:  ${topCounts(s.observeClearsByPolicy)} (observe mode)`);
   }
-  if (s.modes && s.modes.shadow > 0 && s.modes.enforce > 0) {
-    lines.push(`  Modes:        enforce ${s.modes.enforce}, shadow ${s.modes.shadow}`);
+  if (s.modes && s.modes.observe > 0 && s.modes.enforce > 0) {
+    lines.push(`  Modes:        enforce ${s.modes.enforce}, observe ${s.modes.observe}`);
   }
   return lines.join("\n");
 }