failproofai 1.0.8-beta.0 → 1.0.9-beta.0

package/src/hooks/integrations.ts

@@ -14,11 +14,14 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
+  readlinkSync,
+  realpathSync,
   renameSync,
   rmSync,
+  symlinkSync,
   unlinkSync,
 } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { parseDocument, type Document } from "yaml";
@@ -1388,9 +1391,13 @@ function makePiProjectRelativeEntry(extPath: string): string {
 // Hermes loads trusted Python plugins from `<HERMES_HOME>/plugins/<name>/`.
 // The shipped plugin registers Hermes-native hooks and talks directly to the
 // local failproofaid socket, avoiding a fresh CLI process per event. Config is
-// YAML and profile-scoped; install copies the plugin into every profile and
+// YAML and profile-scoped; install LINKS every profile's `plugins/failproofai`
+// to the package's `hermes-plugin/` (so npm upgrades apply with no reinstall,
+// like OpenClaw's `plugins.load.paths`), falling back to a marked copy, and
 // adds `failproofai` to `plugins.enabled`. Legacy shell-hook entries are removed
-// during migration so one tool call is never evaluated twice.
+// during migration so one tool call is never evaluated twice — and because
+// config.yaml shell hooks never reach Hermes cron jobs: each cron fire builds
+// its own hook scope, which discovered plugins join and config hooks do not.
 
 /** One hook entry as stored under a `hooks:` event key in config.yaml. */
 interface HermesHookEntry {
@@ -1409,38 +1416,137 @@ interface HermesPluginsConfig {
 const HERMES_PLUGIN_ID = "failproofai";
 const HERMES_PLUGIN_MARKER = ".failproofai-managed";
 const HERMES_PLUGIN_FILES = ["plugin.yaml", "__init__.py", "client.py", "ledger.py"] as const;
+/** Basename of the plugin directory inside the npm package. */
+const HERMES_PLUGIN_SOURCE_DIR = "hermes-plugin";
 
 function getHermesPluginSourcePath(): string {
   const fromEnv = process.env.FAILPROOFAI_PACKAGE_ROOT;
-  if (fromEnv) return resolve(fromEnv, "hermes-plugin");
-  return resolve(fileURLToPath(import.meta.url), "..", "..", "..", "hermes-plugin");
+  if (fromEnv) return resolve(fromEnv, HERMES_PLUGIN_SOURCE_DIR);
+  return resolve(fileURLToPath(import.meta.url), "..", "..", "..", HERMES_PLUGIN_SOURCE_DIR);
 }
 
 export function hermesPluginPathForSettings(settingsPath: string): string {
   return resolve(dirname(settingsPath), "plugins", HERMES_PLUGIN_ID);
 }
 
-function hasManagedHermesPlugin(settingsPath: string): boolean {
-  const pluginPath = hermesPluginPathForSettings(settingsPath);
+/** `existsSync` follows symlinks, so a dangling link reads as absent. This does not. */
+function pathPresent(path: string): boolean {
   try {
-    if (lstatSync(pluginPath).isSymbolicLink()) return false;
-    if (!existsSync(resolve(pluginPath, HERMES_PLUGIN_MARKER))) return false;
-    return HERMES_PLUGIN_FILES.every((file) => existsSync(resolve(pluginPath, file)));
+    lstatSync(path);
+    return true;
   } catch {
     return false;
   }
 }
 
-function hasHermesPluginMarker(settingsPath: string): boolean {
-  const pluginPath = hermesPluginPathForSettings(settingsPath);
+function hasAllHermesPluginFiles(dir: string): boolean {
+  return HERMES_PLUGIN_FILES.every((file) => existsSync(resolve(dir, file)));
+}
+
+/**
+ * Whether `dir` is a FailproofAI `hermes-plugin` directory (or was one: a link
+ * whose target vanished during an npm upgrade or uninstall is still ours).
+ * The basename is the package layout; the manifest name confirms it when the
+ * target is readable, so a link to someone else's plugin is never claimed.
+ */
+function isFailproofaiHermesPluginSource(dir: string): boolean {
+  if (basename(dir) !== HERMES_PLUGIN_SOURCE_DIR) return false;
+  if (!existsSync(dir)) return true;
   try {
-    return !lstatSync(pluginPath).isSymbolicLink() && existsSync(resolve(pluginPath, HERMES_PLUGIN_MARKER));
+    const manifest = readFileSync(resolve(dir, "plugin.yaml"), "utf8");
+    return /^name:\s*["']?failproofai["']?\s*$/m.test(manifest);
   } catch {
     return false;
   }
 }
 
-function installHermesPlugin(settingsPath: string): void {
+function samePath(a: string, b: string): boolean {
+  if (resolve(a) === resolve(b)) return true;
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What occupies `<profile>/plugins/failproofai`, and whether FailproofAI owns it.
+ *
+ *   • `link`     — a symlink into a FailproofAI package's `hermes-plugin/` (the
+ *                  current install shape: npm upgrades apply with no reinstall).
+ *   • `copy`     — a copied directory carrying the `.failproofai-managed`
+ *                  marker (1.0.6–1.0.8 installs, and the fallback where a
+ *                  symlink cannot be created).
+ *   • `foreign`  — anything else: an unmarked directory, a file, or a symlink
+ *                  somewhere that is not a FailproofAI plugin. Never touched.
+ */
+type HermesPluginState =
+  | { kind: "absent" }
+  | { kind: "link"; target: string; complete: boolean; current: boolean }
+  | { kind: "copy"; complete: boolean }
+  | { kind: "foreign" };
+
+function hermesPluginState(settingsPath: string): HermesPluginState {
+  const pluginPath = hermesPluginPathForSettings(settingsPath);
+  let isLink: boolean;
+  let isDirectory: boolean;
+  try {
+    const stat = lstatSync(pluginPath);
+    isLink = stat.isSymbolicLink();
+    isDirectory = stat.isDirectory();
+  } catch {
+    return { kind: "absent" };
+  }
+  if (isLink) {
+    let target: string;
+    try {
+      target = resolve(dirname(pluginPath), readlinkSync(pluginPath));
+    } catch {
+      return { kind: "foreign" };
+    }
+    if (!isFailproofaiHermesPluginSource(target)) return { kind: "foreign" };
+    return {
+      kind: "link",
+      target,
+      complete: hasAllHermesPluginFiles(target),
+      current: samePath(target, getHermesPluginSourcePath()),
+    };
+  }
+  if (isDirectory && existsSync(resolve(pluginPath, HERMES_PLUGIN_MARKER))) {
+    return { kind: "copy", complete: hasAllHermesPluginFiles(pluginPath) };
+  }
+  return { kind: "foreign" };
+}
+
+function hasManagedHermesPlugin(settingsPath: string): boolean {
+  const state = hermesPluginState(settingsPath);
+  return (state.kind === "link" || state.kind === "copy") && state.complete;
+}
+
+/** Test seam: lets a test make symlink creation fail to exercise the copy fallback. */
+export interface HermesPluginInstallDeps {
+  symlink?: (target: string, path: string) => void;
+}
+
+function defaultHermesSymlink(target: string, path: string): void {
+  // A junction needs no privilege on Windows; the type is ignored elsewhere.
+  symlinkSync(target, path, process.platform === "win32" ? "junction" : "dir");
+}
+
+/**
+ * Put the plugin at `<profile>/plugins/failproofai`, preferring a symlink to
+ * the package's own `hermes-plugin/` so every npm upgrade updates it in place —
+ * the same reason OpenClaw's config points into the package. Hermes' plugin
+ * scan uses `Path.is_dir()`, which follows symlinks, so the link is discovered
+ * like a directory. Falls back to a marked copy when a link cannot be created.
+ *
+ * Only a path FailproofAI owns (a marked copy, or a link into a FailproofAI
+ * `hermes-plugin/`) is ever replaced; anything else throws.
+ */
+export function installHermesPlugin(
+  settingsPath: string,
+  deps: HermesPluginInstallDeps = {},
+): "linked" | "copied" | "unchanged" {
   const source = getHermesPluginSourcePath();
   for (const file of HERMES_PLUGIN_FILES) {
     if (!existsSync(resolve(source, file))) {
@@ -1449,50 +1555,88 @@ function installHermesPlugin(settingsPath: string): void {
   }
 
   const destination = hermesPluginPathForSettings(settingsPath);
-  if (existsSync(destination)) {
-    if (lstatSync(destination).isSymbolicLink() || !existsSync(resolve(destination, HERMES_PLUGIN_MARKER))) {
-      throw new Error(
-        `Refusing to overwrite an unmanaged Hermes plugin at ${destination}. ` +
-          `Move it aside or install FailproofAI under a different Hermes profile.`,
-      );
-    }
+  const existing = hermesPluginState(settingsPath);
+  if (existing.kind === "foreign") {
+    throw new Error(
+      `Refusing to overwrite an unmanaged Hermes plugin at ${destination}. ` +
+        `Move it aside or install FailproofAI under a different Hermes profile.`,
+    );
   }
+  if (existing.kind === "link" && existing.current) return "unchanged";
 
   mkdirSync(dirname(destination), { recursive: true });
   const suffix = `${process.pid}-${Date.now()}`;
   const temporary = `${destination}.install-${suffix}`;
-  const backup = `${destination}.backup-${suffix}`;
-  let movedExisting = false;
+
+  let linked = false;
   try {
+    (deps.symlink ?? defaultHermesSymlink)(source, temporary);
+    linked = true;
+  } catch {
+    rmSync(temporary, { recursive: true, force: true });
+  }
+
+  if (!linked) {
     mkdirSync(temporary, { recursive: true });
-    for (const file of HERMES_PLUGIN_FILES) {
-      cpSync(resolve(source, file), resolve(temporary, file));
+    try {
+      for (const file of HERMES_PLUGIN_FILES) {
+        cpSync(resolve(source, file), resolve(temporary, file));
+      }
+      writeFileSync(
+        resolve(temporary, HERMES_PLUGIN_MARKER),
+        "Managed by failproofai. Remove with `failproofai policies --uninstall --cli hermes`.\n",
+        { encoding: "utf8", mode: 0o600 },
+      );
+    } catch (err) {
+      rmSync(temporary, { recursive: true, force: true });
+      throw err;
     }
-    writeFileSync(
-      resolve(temporary, HERMES_PLUGIN_MARKER),
-      "Managed by failproofai. Remove with `failproofai policies --uninstall --cli hermes`.\n",
-      { encoding: "utf8", mode: 0o600 },
-    );
-    if (existsSync(destination)) {
+  }
+
+  // A link replacing a link is one atomic rename. Anything replacing a
+  // directory (or a link replaced by a directory) cannot rename over it, so
+  // the old entry is moved aside first and restored if the swap fails.
+  if (linked && (existing.kind === "absent" || existing.kind === "link")) {
+    try {
+      renameSync(temporary, destination);
+    } catch (err) {
+      rmSync(temporary, { force: true });
+      throw err;
+    }
+    return "linked";
+  }
+
+  const backup = `${destination}.backup-${suffix}`;
+  let movedExisting = false;
+  try {
+    if (pathPresent(destination)) {
       renameSync(destination, backup);
       movedExisting = true;
     }
     renameSync(temporary, destination);
+    // fs.rm never follows a symlink, so a backed-up link removes only itself.
     if (movedExisting) rmSync(backup, { recursive: true, force: true });
   } catch (err) {
     rmSync(temporary, { recursive: true, force: true });
-    if (movedExisting && !existsSync(destination) && existsSync(backup)) {
+    if (movedExisting && !pathPresent(destination) && pathPresent(backup)) {
       renameSync(backup, destination);
     }
     throw err;
   }
+  return linked ? "linked" : "copied";
 }
 
 function removeManagedHermesPlugin(settingsPath: string): boolean {
   const pluginPath = hermesPluginPathForSettings(settingsPath);
+  const state = hermesPluginState(settingsPath);
+  if (state.kind === "link") {
+    // Only the link goes; the package directory it points at is npm's.
+    unlinkSync(pluginPath);
+    return true;
+  }
   // The marker is the ownership boundary. Remove even an incomplete managed
-  // install so an interrupted copy can always be repaired or uninstalled.
-  if (!hasHermesPluginMarker(settingsPath)) return false;
+  // copy so an interrupted install can always be repaired or uninstalled.
+  if (state.kind !== "copy") return false;
   rmSync(pluginPath, { recursive: true, force: true });
   return true;
 }
@@ -1549,13 +1693,163 @@ function hermesConfigState(settingsPath: string): {
   };
 }
 
+/**
+ * Enable the native plugin in one profile's config and drop FailproofAI's
+ * legacy shell hooks. A native plugin and the legacy shell bridge running
+ * together would evaluate every event twice. Only failproofai-owned shell
+ * entries are removed; unrelated operator hooks remain intact.
+ */
+function enableHermesPluginInDoc(doc: Document): void {
+  removeLegacyHermesHooks(doc);
+
+  const js = (doc.toJS() ?? {}) as { plugins?: HermesPluginsConfig };
+  const plugins: HermesPluginsConfig =
+    js.plugins && typeof js.plugins === "object" ? js.plugins : {};
+  const enabled = Array.isArray(plugins.enabled) ? [...plugins.enabled] : [];
+  if (!enabled.includes(HERMES_PLUGIN_ID)) enabled.push(HERMES_PLUGIN_ID);
+  plugins.enabled = enabled;
+  if (Array.isArray(plugins.disabled)) {
+    plugins.disabled = plugins.disabled.filter((name) => name !== HERMES_PLUGIN_ID);
+    if (plugins.disabled.length === 0) delete plugins.disabled;
+  }
+  doc.set("plugins", plugins);
+}
+
+export type HermesMigrationStatus =
+  /** Brought to the linked-plugin state by this run. */
+  | "migrated"
+  /** Already linked to this package, enabled, and free of shell hooks. */
+  | "current"
+  /** No FailproofAI integration in this profile — left alone. */
+  | "untouched"
+  /** Needs migrating, but the daemon cannot serve the native plugin. Nothing changed. */
+  | "blocked"
+  /** Could not be migrated (unmanaged plugin in the way, unreadable config, I/O error). */
+  | "failed";
+
+export interface HermesProfileMigration {
+  name: string;
+  home: string;
+  status: HermesMigrationStatus;
+  detail: string;
+  /** Legacy config.yaml shell hooks are still in place after this run. */
+  legacyShellHooksRemain: boolean;
+}
+
+/**
+ * The upgrade half `failproofai update` owes Hermes: bring every profile that
+ * already uses FailproofAI (legacy shell hooks, a copied plugin, or a link) to
+ * the linked-plugin state. Profiles with no FailproofAI integration are never
+ * touched — an update must not opt a profile in.
+ *
+ * `daemonSupportsPolicyEvaluation` is asked at most once, and only when some
+ * profile needs changing. When it says no, NOTHING is changed: removing the
+ * shell hooks in favour of a plugin whose daemon cannot answer would fail every
+ * tool call closed (the same gate `policies --install` applies).
+ */
+export async function migrateHermesProfiles(opts: {
+  daemonSupportsPolicyEvaluation: () => Promise<boolean>;
+  installDeps?: HermesPluginInstallDeps;
+}): Promise<HermesProfileMigration[]> {
+  const results: HermesProfileMigration[] = [];
+  let daemonOk: boolean | undefined;
+  for (const profile of listHermesProfiles()) {
+    if (!existsSync(profile.home)) continue;
+    const settingsPath = resolve(profile.home, "config.yaml");
+    const pluginPath = hermesPluginPathForSettings(settingsPath);
+    const config = hermesConfigState(settingsPath);
+    const plugin = hermesPluginState(settingsPath);
+    const ours = plugin.kind === "link" || plugin.kind === "copy";
+    const base = { name: profile.name, home: profile.home };
+    const legacy = config.legacyShellHookPresent;
+
+    if (!legacy && !ours && !config.pluginEnabled) {
+      results.push({ ...base, status: "untouched", detail: "no failproofai integration", legacyShellHooksRemain: false });
+      continue;
+    }
+    if (plugin.kind === "link" && plugin.current && plugin.complete && config.pluginEnabled && !legacy) {
+      results.push({ ...base, status: "current", detail: "already linked", legacyShellHooksRemain: false });
+      continue;
+    }
+    if (plugin.kind === "foreign") {
+      results.push({
+        ...base,
+        status: "failed",
+        detail:
+          `an unmanaged plugin occupies ${pluginPath}` +
+          (legacy ? "; shell hooks left in place (cron jobs are not checked)" : ""),
+        legacyShellHooksRemain: legacy,
+      });
+      continue;
+    }
+    if (existsSync(settingsPath)) {
+      const errors = parseDocument(readFileSync(settingsPath, "utf8")).errors;
+      if (errors.length > 0) {
+        results.push({
+          ...base,
+          status: "failed",
+          detail: `${settingsPath} does not parse as YAML; left untouched`,
+          legacyShellHooksRemain: legacy,
+        });
+        continue;
+      }
+    }
+
+    if (daemonOk === undefined) daemonOk = await opts.daemonSupportsPolicyEvaluation();
+    if (!daemonOk) {
+      results.push({
+        ...base,
+        status: "blocked",
+        detail: legacy
+          ? "daemon lacks native policy evaluation; shell hooks left in place (cron jobs are not checked)"
+          : "daemon lacks native policy evaluation; the plugin here cannot get verdicts",
+        legacyShellHooksRemain: legacy,
+      });
+      continue;
+    }
+
+    try {
+      // Plugin first, config second: the shell hooks are only removed once the
+      // plugin that replaces them is on disk.
+      const mode = installHermesPlugin(settingsPath, opts.installDeps);
+      const doc = readYamlDoc(settingsPath);
+      enableHermesPluginInDoc(doc);
+      writeYamlDoc(settingsPath, doc);
+      const from = legacy
+        ? "shell hooks"
+        : plugin.kind === "copy"
+          ? "copied plugin"
+          : plugin.kind === "link"
+            ? "old plugin link"
+            : "enabled but missing plugin";
+      const to = mode === "copied" ? "plugin copy (symlink not possible here)" : "linked plugin";
+      results.push({ ...base, status: "migrated", detail: `${from} → ${to}`, legacyShellHooksRemain: false });
+    } catch (err) {
+      results.push({
+        ...base,
+        status: "failed",
+        detail: err instanceof Error ? err.message : String(err),
+        legacyShellHooksRemain: hermesConfigState(settingsPath).legacyShellHookPresent,
+      });
+    }
+  }
+  return results;
+}
+
 export interface HermesProfileHealth {
   name: string;
   home: string;
   settingsPath: string;
   pluginInstalled: boolean;
+  /** How the plugin is installed: a link into the package, a copy, or neither. */
+  pluginMode: "link" | "copy" | null;
   pluginEnabled: boolean;
   legacyShellHookPresent: boolean;
+  /**
+   * Still enforced only by legacy config.yaml shell hooks. Hermes cron jobs run
+   * with none of those, so their tool calls go unchecked.
+   */
+  cronUnchecked: boolean;
   healthy: boolean;
 }
 
@@ -1564,15 +1858,19 @@ export function hermesProfileHealth(): HermesProfileHealth[] {
   return listHermesProfiles().map((profile) => {
     const settingsPath = resolve(profile.home, "config.yaml");
     const config = hermesConfigState(settingsPath);
-    const pluginInstalled = hasManagedHermesPlugin(settingsPath);
+    const plugin = hermesPluginState(settingsPath);
+    const pluginInstalled = (plugin.kind === "link" || plugin.kind === "copy") && plugin.complete;
+    const pluginWorks = pluginInstalled && config.pluginEnabled;
     return {
       name: profile.name,
       home: profile.home,
       settingsPath,
       pluginInstalled,
+      pluginMode: plugin.kind === "link" || plugin.kind === "copy" ? plugin.kind : null,
       pluginEnabled: config.pluginEnabled,
       legacyShellHookPresent: config.legacyShellHookPresent,
-      healthy: pluginInstalled && config.pluginEnabled && !config.legacyShellHookPresent,
+      cronUnchecked: config.legacyShellHookPresent && !pluginWorks,
+      healthy: pluginWorks && !config.legacyShellHookPresent,
     };
   });
 }
@@ -1582,13 +1880,25 @@ export function hermesProfileStatusRows(): Array<[string, string]> {
   return hermesProfileHealth()
     .filter((profile) => existsSync(profile.home))
     .map((profile) => {
+      const label = "hermes/" + profile.name;
+      if (profile.cronUnchecked) {
+        // Not a cosmetic leftover: the shell-hook integration does not reach
+        // cron jobs at all, so this profile has an unenforced path.
+        return [
+          label,
+          "UNHEALTHY — legacy shell hooks: Hermes cron jobs are not checked. Run `failproofai update`",
+        ];
+      }
       const problems: string[] = [];
       if (!profile.pluginInstalled) problems.push("plugin files missing or incomplete");
       if (!profile.pluginEnabled) problems.push("plugin not enabled");
       if (profile.legacyShellHookPresent) problems.push("legacy shell hook also present");
+      if (problems.length > 0) return [label, "UNHEALTHY — " + problems.join("; ")];
       return [
-        "hermes/" + profile.name,
-        problems.length === 0 ? "native plugin enabled" : "UNHEALTHY — " + problems.join("; "),
+        label,
+        profile.pluginMode === "copy"
+          ? "native plugin enabled (copied — `failproofai update` links it so upgrades apply)"
+          : "native plugin enabled",
       ];
     });
 }
@@ -1641,23 +1951,7 @@ export const hermes: Integration = {
   isFailproofaiHook: isMarkedHook,
 
   writeHookEntries(settings) {
-    const doc = settings as unknown as Document;
-    // A native plugin and the legacy shell bridge running together would
-    // evaluate every event twice. Remove only failproofai-owned shell entries;
-    // unrelated operator hooks remain intact.
-    removeLegacyHermesHooks(doc);
-
-    const js = (doc.toJS() ?? {}) as { plugins?: HermesPluginsConfig };
-    const plugins: HermesPluginsConfig =
-      js.plugins && typeof js.plugins === "object" ? js.plugins : {};
-    const enabled = Array.isArray(plugins.enabled) ? [...plugins.enabled] : [];
-    if (!enabled.includes(HERMES_PLUGIN_ID)) enabled.push(HERMES_PLUGIN_ID);
-    plugins.enabled = enabled;
-    if (Array.isArray(plugins.disabled)) {
-      plugins.disabled = plugins.disabled.filter((name) => name !== HERMES_PLUGIN_ID);
-      if (plugins.disabled.length === 0) delete plugins.disabled;
-    }
-    doc.set("plugins", plugins);
+    enableHermesPluginInDoc(settings as unknown as Document);
   },
 
   removeHooksFromFile(settingsPath) {

package/src/hooks/jev-activity.ts

@@ -57,7 +57,7 @@ export const JEV_ACTIVITY_KEYS = [
 
 const EVALUATORS = new Set(["jev", "jev-fallback"]);
 const DECISIONS = new Set(["allow", "instruct", "deny"]);
-const MODES = new Set(["shadow", "enforce"]);
+const MODES = new Set(["observe", "enforce"]);
 
 /**
  * A reason's leading code — lowercase kebab-case — either alone or followed by
@@ -374,9 +374,9 @@ export function describeJevActivity(raw: JevActivityFields): string[] | null {
   if (e.jevDecision) facts.push(`Jev verdict: ${e.jevDecision}`);
   const cleared = e.jevCleared ?? [];
   if (cleared.length > 0) {
-    facts.push(`${e.jevMode === "shadow" ? "would have cleared" : "cleared"} ${cleared.join(", ")}`);
+    facts.push(`${e.jevMode === "observe" ? "would have cleared" : "cleared"} ${cleared.join(", ")}`);
   }
-  if (e.jevMode === "shadow") facts.push("shadow mode: the regex result was enforced");
+  if (e.jevMode === "observe") facts.push("observe mode: the regex result was enforced");
   if (e.jevLatencyMs !== undefined) facts.push(`${e.jevLatencyMs} ms`);
   if (e.jevModel) facts.push(e.jevModel);
   // Answered, but nothing this build can show (a verdict in a shape it cannot read).

package/src/hooks/jev-cli.ts

@@ -186,7 +186,7 @@ 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 setup --provider failproofai [--mode off|observe|enforce]   (FailproofAI Cloud: no key, no URL)",
   "  failproofai jev status [--json]",
   "  failproofai jev test [--json]",
   "  failproofai jev models [--provider <kind>] [--url <base>] [--json]",
@@ -269,7 +269,7 @@ 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";
+    : "observe — Jev is asked and logged; the regex result is what is enforced";
 }
 
 /**
@@ -458,12 +458,11 @@ export function jevStatsLines(stats: JevStats | null, opts: RenderOpts = {}): st
       .join(", ");
   const clears = byPolicy(stats.clearsByPolicy);
   // `clearsByPolicy` counts clears that CHANGED an outcome, which only enforce
-  // mode can do; in shadow mode every clear Jev would have made is in
-  // `shadowClearsByPolicy` instead and this one is empty. Printing the first
-  // alone would tell a shadow user "cleared nothing" — the one number they
-  // turned shadow mode on to watch. The field is optional because the stats
-  // module T1 builds against does not have it yet (T8 adds it).
-  const shadowClears = byPolicy((stats as { shadowClearsByPolicy?: Record<string, number> }).shadowClearsByPolicy);
+  // mode can do; in observe mode every clear Jev would have made is in
+  // `observeClearsByPolicy` instead and this one is empty. Printing the first
+  // alone would tell an observe-mode user "cleared nothing" — the one number
+  // they turned observe mode on to watch.
+  const observeClears = byPolicy(stats.observeClearsByPolicy);
   const ms = (v: number | null) => (v === null ? "—" : `${Math.round(v)} ms`);
   return stack(
     heading,
@@ -473,7 +472,7 @@ export function jevStatsLines(stats: JevStats | null, opts: RenderOpts = {}): st
         ["fell back to regex", `${pct(stats.fallbackRate)}${reasons ? ` (${reasons})` : ""}`],
         ["latency", `p50 ${ms(stats.latencyP50Ms)} · p95 ${ms(stats.latencyP95Ms)}`],
         ["cleared", clears || "nothing"],
-        ...(shadowClears ? ([["would have cleared (shadow)", shadowClears]] as Array<[string, string]>) : []),
+        ...(observeClears ? ([["would have cleared (observe)", observeClears]] as Array<[string, string]>) : []),
       ],
       opts,
     ),
@@ -1206,11 +1205,10 @@ async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts:
   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
+  // Observe 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;
+  next.mode = values.get("--mode") ?? (sameProvider && typeof next.mode === "string" ? next.mode : "observe");
   if (values.has("--timeout-ms")) {
     const rawTimeout = values.get("--timeout-ms") as string;
     const n = Number(rawTimeout);
@@ -1247,7 +1245,7 @@ async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts:
           ]
         : [
             "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:",
+            "Connect it with one that does (the \"machine\" preset) — that also turns Jev on, in observe mode, when there is no jev.json yet:",
           ]),
       "  failproofai config --token <key>",
       "",
@@ -1332,7 +1330,7 @@ async function cloudSetup(values: Map<string, string>, bools: Set<string>, opts:
 /**
  * Where a file would send requests, for display, whether or not it loads. Only
  * the routing fields are used — the key and model do not decide where requests
- * go — and shadow mode lets a loopback http URL through validation. Null when
+ * go — and observe mode lets a loopback http URL through validation. Null when
  * it names nothing recognisable.
  */
 /**
@@ -1366,7 +1364,7 @@ function displayOnlyCloudOrigin(routing: { provider?: unknown; baseUrl?: unknown
 
 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", ...displayOnlyCloudOrigin(raw) };
+  const routing: Record<string, unknown> = { provider: raw.provider, apiKey: ENV_KEY_STAND_IN, mode: "observe", ...displayOnlyCloudOrigin(raw) };
   if (raw.baseUrl !== undefined) routing.baseUrl = raw.baseUrl;
   if (raw.accountId !== undefined) routing.accountId = raw.accountId;
   try {
@@ -1499,6 +1497,8 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
                 enabled: coverage.enabled,
                 reviewable: coverage.reviewable,
                 customPolicyFiles: coverage.customFiles,
+                // Checks an installed pack gives Jev to ask; 0 means Jev is inert.
+                jevChecks: coverage.jevChecks,
                 problem: coverageProblem,
               },
             }
@@ -1599,7 +1599,7 @@ async function status(argv: string[], opts: RenderOpts): Promise<JevCliResult> {
           ],
           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),
+        nextStep("failproofai jev setup --mode observe", "Switch it back on (observe logs Jev and keeps enforcing regex; enforce lets it clear), here or from the dashboard:", opts),
         legacyNote,
         jevStatsLines(stats, opts),
       ),
@@ -1786,7 +1786,7 @@ async function test(argv: string[], deps: JevCliDeps, opts: RenderOpts): Promise
       : inspection.status === "key-missing"
         ? "failproofai jev setup --key-stdin < key-file"
         : inspection.status === "off"
-          ? "failproofai jev setup --mode shadow"
+          ? "failproofai jev setup --mode observe"
           : inspection.status === "not-connected" || inspection.status === "key-lacks-jev"
             ? "failproofai config --token <key>"
             : "failproofai jev setup --provider <kind> --key-stdin";