failproofai 1.0.0-beta.2 → 1.0.0-beta.4

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

@@ -12,29 +12,40 @@
  */
 import { resolve, isAbsolute, basename } from "node:path";
 import { existsSync, readdirSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { homedir } from "node:os";
+import { createHash } from "node:crypto";
 import { hookLogWarn, hookLogError, hookLogInfo } from "./hook-logger";
-import { getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
+import { customPolicies, getCustomHooks, clearCustomHooks } from "./custom-hooks-registry";
 import { findDistIndex, rewriteFileTree, TMP_SUFFIX, cleanupTmpFiles } from "./loader-utils";
 import { findProjectConfigDir } from "./hooks-config";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 import type { CustomHook } from "./policy-types";
+import type { CloudManagedPolicyArtifact } from "./cloud-managed-policies";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
 
 /** Regex matching convention policy filenames: *policies.{js,mjs,ts} */
 const CONVENTION_FILE_RE = /policies\.(js|mjs|ts)$/;
 
-/**
- * Monotonic counter used to cache-bust each dynamic import. Loading N files
- * creates N module instances rather than reusing one; every caller here is
- * either a one-shot CLI command or a short-lived hook process, so the
- * lifetime cost is bounded by the process, not by uptime.
- */
+/** Monotonic suffix for physically distinct temporary module trees. Bun
+ * ignores URL query strings when caching imports, so a query-only cache
+ * buster silently drops custom policies after the first request in the warm
+ * daemon worker. A unique filename is honored by both Bun and Node. */
 let loadSequence = 0;
 
+interface CachedPolicyModule {
+  fingerprint: string;
+  hooks: CustomHook[];
+}
+
+/** One retained module instance per source entry. Reusing its registered hook
+ * functions prevents an unbounded ESM module-cache leak in the resident worker.
+ * A source-tree change replaces this entry and imports one new module. */
+const policyModuleCache = new Map<string, CachedPolicyModule>();
+
 /** Script extensions we could load, used to spot near-miss filenames. */
 const LOADABLE_EXT_RE = /\.(js|mjs|ts)$/;
 
@@ -101,23 +112,27 @@ async function loadSingleFile(
     const distIndex = await findDistIndex();
     const distUrl = distIndex ? pathToFileURL(distIndex).href : null;
 
-    tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex);
-
-    const entryTmp = absPath + TMP_SUFFIX;
-    // Cache-bust the specifier. NOTE this works under Node but NOT under Bun,
-    // which caches by resolved path and ignores the query — and the shipped
-    // binary runs under Bun. It is kept because it makes repeat loads behave
-    // the same on both runtimes where it can, but nothing may DEPEND on a
-    // repeat load re-executing; callers dedupe paths instead (see above).
-    // The temp path is deterministic, so a second
-    // load of the same file inside one process hit the ESM module cache, the
-    // module body never re-ran, no `customPolicies.add` fired, and the caller
-    // saw zero hooks — indistinguishable from a broken policy file. That is
-    // exactly what `failproofai policies` rendered as "failed to load" for
-    // every file when it walked a shared project/user directory twice.
-    // A distinct query string makes it a distinct module to the loader.
-    const fileUrl = `${pathToFileURL(entryTmp).href}?v=${++loadSequence}`;
+    const sequence = ++loadSequence;
+    const tmpSuffix = `${TMP_SUFFIX}.${process.pid}.${sequence}.mjs`;
+    tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex, tmpSuffix);
+
+    const fingerprint = await fingerprintTemporaryTree(tmpFiles, tmpSuffix);
+    const cached = policyModuleCache.get(absPath);
+    if (cached?.fingerprint === fingerprint) {
+      for (const hook of cached.hooks) customPolicies.add({ ...hook });
+      return;
+    }
+
+    const entryTmp = absPath + tmpSuffix;
+    const fileUrl = pathToFileURL(entryTmp).href;
+    const hooksBefore = getCustomHooks().length;
     await import(/* webpackIgnore: true */ fileUrl);
+    policyModuleCache.set(absPath, {
+      fingerprint,
+      hooks: getCustomHooks()
+        .slice(hooksBefore)
+        .map((hook) => ({ ...hook })),
+    });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const errorType = /Cannot find module|MODULE_NOT_FOUND|ENOENT/i.test(msg)
@@ -139,6 +154,18 @@ async function loadSingleFile(
   }
 }
 
+async function fingerprintTemporaryTree(tmpFiles: string[], tmpSuffix: string): Promise<string> {
+  const hash = createHash("sha256");
+  for (const tmpFile of [...tmpFiles].sort()) {
+    // The generated filenames change per load. Normalize both the logical path
+    // and rewritten import specifiers so identical source graphs hash equally.
+    hash.update(tmpFile.replaceAll(tmpSuffix, TMP_SUFFIX));
+    const contents = await readFile(tmpFile, "utf8");
+    hash.update(contents.replaceAll(tmpSuffix, TMP_SUFFIX));
+  }
+  return hash.digest("hex");
+}
+
 /**
  * Load a single explicit custom hooks file (legacy API).
  * Clears the registry, loads the file, returns registered hooks.
@@ -214,7 +241,11 @@ function warnSkippedPolicyFiles(dir: string, scope: "project" | "user"): void {
 
 export async function loadAllCustomHooks(
   customPoliciesPaths: string | string[] | undefined,
-  opts?: { sessionCwd?: string; customPoliciesEnabled?: boolean },
+  opts?: {
+    sessionCwd?: string;
+    customPoliciesEnabled?: boolean;
+    cloudManagedPolicies?: CloudManagedPolicyArtifact[];
+  },
 ): Promise<LoadAllResult> {
   clearCustomHooks();
 
@@ -235,6 +266,9 @@ export async function loadAllCustomHooks(
   // twice per event. Seeded by the explicit path below and consulted by both
   // convention passes.
   const loadedPaths = new Set<string>();
+  const cloudManagedByPath = new Map(
+    (opts?.cloudManagedPolicies ?? []).map((policy) => [resolve(policy.path), policy]),
+  );
 
   // 1. Explicit custom policy paths. Accept a string for callers/configs using
   // the legacy singular form.
@@ -250,7 +284,17 @@ export async function loadAllCustomHooks(
         const hooksBefore = getCustomHooks().length;
         await loadSingleFile(absPath);
         for (const hook of getCustomHooks().slice(hooksBefore)) {
-          (hook as CustomHook & { __policyId?: string }).__policyId = customPolicyId(absPath, hook.name);
+          const cloudManaged = cloudManagedByPath.get(absPath);
+          const tagged = hook as CustomHook & {
+            __policyId?: string;
+            __cloudManaged?: CloudManagedPolicyArtifact;
+          };
+          if (cloudManaged) {
+            tagged.__cloudManaged = cloudManaged;
+            tagged.__policyId = `cloud:${cloudManaged.id}@${cloudManaged.revision}:${hook.name}`;
+          } else {
+            tagged.__policyId = customPolicyId(absPath, hook.name);
+          }
         }
       }
     } else {

package/src/hooks/daemon-client.ts

@@ -17,6 +17,7 @@ import { resolve } from "node:path";
 import { homedir } from "node:os";
 import type { IntegrationType } from "./types";
 import { readHooksConfig } from "./hooks-config";
+import { existsSync } from "node:fs";
 
 const PROTOCOL_VERSION = 1;
 
@@ -66,6 +67,23 @@ export interface DaemonHookResponse {
   stderr: string;
 }
 
+/**
+ * Whether a daemon is listening, regardless of how it was started.
+ *
+ * Distinct from `daemonServiceStatus()`, which asks the service manager. A
+ * daemon run by hand — during development, or from a container — is invisible
+ * to that check but is very much running and pulling policy, so reporting "not
+ * installed, so nothing will be pulled" at someone whose machine is actively
+ * enforcing is simply false.
+ */
+export function daemonSocketPresent(): boolean {
+  try {
+    return existsSync(socketPath());
+  } catch {
+    return false;
+  }
+}
+
 function socketPath(): string {
   if (process.env.FAILPROOFAI_DAEMON_SOCKET) return process.env.FAILPROOFAI_DAEMON_SOCKET;
   return resolve(homedir(), ".failproofai", "run", "failproofaid.sock");

package/src/hooks/daemon-download.ts

@@ -1,20 +1,31 @@
 /**
- * Fetches the compiled `failproofaid` binary for this platform from the
- * GitHub Release that matches this CLI's own version.
+ * Gets the compiled `failproofaid` binary for this platform onto disk, from
+ * whichever of its two channels can supply it.
  *
- * Why a download rather than a dependency: the daemon is a 4-way
- * cross-compiled Rust binary, and shipping it through npm means four
- * per-platform packages that every install resolves, an npm org to own the
- * scope, and a second publish channel that can silently drift from the first
- * (it already did — the platform packages were declared as
- * `optionalDependencies` and never published, so every install of them 404'd).
- * The release assets have to exist for standalone installs regardless, so
- * pointing the CLI at the same artifacts leaves exactly one channel.
+ * **npm first.** The four binaries publish as
+ * `@failproofai/failproofaid-<os>-<arch>` platform packages, pinned as
+ * `optionalDependencies` of this package, so `npm install failproofai` has
+ * usually already brought down the one matching this machine — `os`/`cpu`
+ * make npm skip the other three. Copying that file costs no network at all,
+ * which is the only thing that works behind a proxy or air-gapped.
  *
- * The URL is *constructed*, never discovered — no API call, no `releases/latest`
- * redirect, no rate limit, and no chance of fetching a daemon built from
- * different source than the CLI talking to it: the tag is this package's own
- * version, so a CLI upgrade downloads its own matching binary.
+ * **The GitHub Release second.** `failproofaid-<os>-<arch>.gz` plus a
+ * `SHA256SUMS` manifest are attached to the release tagged with this CLI's own
+ * version. That channel has to exist regardless — it is how anyone installs
+ * the daemon standalone, and how an install that skipped optional dependencies
+ * still gets one.
+ *
+ * The pair failed once before in a way worth keeping in mind: the platform
+ * packages were declared as `optionalDependencies` and never published, so
+ * every install resolved four 404s (see CHANGELOG 1.0.0-beta.3). What makes
+ * them safe now is that `scripts/build-daemon-packages.mjs` publishes them
+ * *before* the root package that pins them, and fails the release if it
+ * cannot — the names always exist by the time anything depends on them.
+ *
+ * The download URL is *constructed*, never discovered — no API call, no
+ * `releases/latest` redirect, no rate limit, and no chance of fetching a daemon
+ * built from different source than the CLI talking to it: the tag is this
+ * package's own version, so a CLI upgrade fetches its own matching binary.
  *
  * Everything here fails closed and never throws. A daemon that cannot be
  * fetched leaves the machine on the in-process path it was already using;
@@ -22,9 +33,10 @@
  * this writes an executable that a service manager will then run at login.
  */
 import { createHash } from "node:crypto";
-import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { gunzipSync } from "node:zlib";
 import { version } from "../../package.json";
 import type { PlatformKey } from "./daemon-service";
@@ -82,6 +94,114 @@ export interface DaemonDownloadResult {
   error?: string;
 }
 
+/** The npm package carrying the daemon binary for one platform. */
+export function platformPackageName(key: PlatformKey): string {
+  return `@failproofai/failproofaid-${key}`;
+}
+
+/**
+ * Locates the binary inside the installed platform package, or null.
+ *
+ * Resolution is anchored at `FAILPROOFAI_PACKAGE_ROOT` (set by
+ * `bin/failproofai.mjs` and the bundled `dist/cli.mjs`) rather than at
+ * `import.meta.url`, which does not survive the CJS bundle. Node's algorithm
+ * walks up from there, which covers both real layouts: a global install nests
+ * its dependencies at `<root>/node_modules/@failproofai/…`, a local one hoists
+ * them to `<project>/node_modules/@failproofai/…`.
+ *
+ * The specifier is *computed*, deliberately. A literal would make the bundler
+ * try to resolve a package that is optional, platform-specific, and absent on
+ * three machines out of four at build time.
+ */
+export function npmPlatformBinaryPath(key: PlatformKey): string | null {
+  const packageRoot = process.env.FAILPROOFAI_PACKAGE_ROOT;
+  if (!packageRoot) return null;
+  const name = platformPackageName(key);
+
+  try {
+    const requireFromRoot = createRequire(resolve(packageRoot, "package.json"));
+    const found = platformPackageBinary(dirname(requireFromRoot.resolve(`${name}/package.json`)));
+    if (found) return found;
+  } catch {
+    // Not installed (the common case on a machine that skipped optional
+    // dependencies), or a resolver that cannot see it. The direct check below
+    // is the fallback, not a failure.
+  }
+
+  return platformPackageBinary(resolve(packageRoot, "node_modules", name));
+}
+
+/**
+ * The binary inside one candidate platform-package directory, if it is the
+ * right one.
+ *
+ * The version check is not belt-and-braces. npm pins the exact version, but a
+ * workspace holding two `failproofai` versions can hoist the other one's
+ * platform package to the top of the tree — and installing that binary under
+ * *this* version's filename would put a daemon built from different source
+ * behind a CLI that believes it matches, which is the single thing the
+ * versioned install path exists to prevent. A mismatch falls through to the
+ * download, whose URL is pinned to this version.
+ */
+function platformPackageBinary(dir: string): string | null {
+  try {
+    const manifest = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8")) as {
+      version?: string;
+    };
+    if (manifest.version !== version) return null;
+  } catch {
+    return null;
+  }
+  const candidate = resolve(dir, "bin", "failproofaid");
+  return existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Writes the daemon binary to its versioned path.
+ *
+ * Shared by both channels so a binary lands identically however it arrived:
+ * staged in the same directory as the target (so the install is an atomic
+ * rename within one filesystem, never a half-written executable a service
+ * manager could pick up), mode 0755, pid-suffixed so two concurrent wizards
+ * stay off each other's file.
+ */
+function installBinaryBytes(binary: Buffer): string {
+  const target = installedBinaryPath();
+  const tempPath = `${target}.${process.pid}.tmp`;
+  try {
+    mkdirSync(daemonBinaryDir(), { recursive: true });
+    writeFileSync(tempPath, binary);
+    chmodSync(tempPath, 0o755);
+    renameSync(tempPath, target);
+    return target;
+  } catch (err) {
+    rmSync(tempPath, { force: true });
+    throw err;
+  }
+}
+
+/**
+ * Installs the daemon from the npm platform package, if one is present.
+ *
+ * No checksum step, unlike the download: npm verified the tarball's integrity
+ * against the registry when it installed it, and this file never crossed the
+ * network on its own.
+ *
+ * Deliberately NOT gated on `FAILPROOFAI_NO_DOWNLOAD` — that variable exists
+ * so an air-gapped machine does not reach out, and this is a local copy. On
+ * exactly those machines it is the only channel that can work.
+ */
+export function installFromNpmPackage(key: PlatformKey): DaemonDownloadResult {
+  const source = npmPlatformBinaryPath(key);
+  if (!source) return { error: `${platformPackageName(key)} is not installed` };
+  try {
+    return { path: installBinaryBytes(readFileSync(source)) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: `failed to install failproofaid from ${source}: ${message}` };
+  }
+}
+
 async function fetchBytes(url: string): Promise<Buffer> {
   const response = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
   if (!response.ok) throw new Error(`GET ${url} returned ${response.status}`);
@@ -118,10 +238,6 @@ export async function downloadFailproofaidBinary(key: PlatformKey): Promise<Daem
   }
 
   const assetName = `failproofaid-${key}.gz`;
-  // Same directory as the target so the install is a rename within one
-  // filesystem — atomic, and never a half-written binary a service manager
-  // could pick up. The pid keeps two concurrent wizards off each other's file.
-  const tempPath = `${target}.${process.pid}.tmp`;
 
   try {
     const [asset, manifest] = await Promise.all([
@@ -138,14 +254,8 @@ export async function downloadFailproofaidBinary(key: PlatformKey): Promise<Daem
       return { error: `checksum mismatch for ${assetName} (expected ${expected}, got ${actual})` };
     }
 
-    const binary = gunzipSync(asset);
-    mkdirSync(daemonBinaryDir(), { recursive: true });
-    writeFileSync(tempPath, binary);
-    chmodSync(tempPath, 0o755);
-    renameSync(tempPath, target);
-    return { path: target };
+    return { path: installBinaryBytes(gunzipSync(asset)) };
   } catch (err) {
-    rmSync(tempPath, { force: true });
     const message = err instanceof Error ? err.message : String(err);
     return { error: `failed to download failproofaid v${version} for ${key}: ${message}` };
   }

package/src/hooks/daemon-service.ts

@@ -22,7 +22,7 @@ import { resolve, dirname } from "node:path";
 import { execFileSync } from "node:child_process";
 import { hookLogWarn } from "./hook-logger";
 import { getConfigPathForScope } from "./hooks-config";
-import { downloadFailproofaidBinary, installedBinaryPath } from "./daemon-download";
+import { downloadFailproofaidBinary, installFromNpmPackage, installedBinaryPath } from "./daemon-download";
 
 /**
  * Every `systemctl --user` / `launchctl` call is bounded. Both talk to a
@@ -145,13 +145,19 @@ export function resolveFailproofaidBinaryPath(): string | null {
 }
 
 /**
- * Resolves the binary, downloading it from this version's release if it is
- * not already on disk.
+ * Resolves the binary, installing one if it is not already on disk.
  *
- * Only the install path calls this. The npm package ships no binary — it is
- * one CLI tarball for every platform — so `failproofai config` choosing the
- * global scope is the moment a machine that opted into a daemon actually
- * acquires one.
+ * Only the install path calls this — `failproofai config` choosing the global
+ * scope is the moment a machine that opted into a daemon actually acquires
+ * one. Two channels, in this order:
+ *
+ *   1. The `@failproofai/failproofaid-<os>-<arch>` platform package, which a
+ *      plain `npm install failproofai` already brought down as an optional
+ *      dependency. No network, so it is also the only channel that works
+ *      air-gapped or behind a proxy that blocks github.com.
+ *   2. The GitHub Release asset for this exact version, checksum-verified.
+ *      Covers installs that skipped optional dependencies, older tarballs, and
+ *      anyone installing the daemon standalone.
  */
 export async function ensureFailproofaidBinary(): Promise<{ path?: string; reason?: string }> {
   const existing = resolveFailproofaidBinaryPath();
@@ -162,9 +168,18 @@ export async function ensureFailproofaidBinary(): Promise<{ path?: string; reaso
     return { reason: `failproofaid has no prebuilt binary for ${process.platform}/${process.arch}` };
   }
 
+  const fromNpm = installFromNpmPackage(key);
+  if (fromNpm.path) return { path: fromNpm.path };
+
   const result = await downloadFailproofaidBinary(key);
   if (result.path) return { path: result.path };
-  return { reason: result.error ?? "failproofaid binary could not be downloaded" };
+  // Both channels are worth reporting: "not installed" alone reads as a broken
+  // package, and the download error alone hides that npm could have supplied it.
+  return {
+    reason: result.error
+      ? `${result.error} (${fromNpm.error})`
+      : "failproofaid binary could not be installed",
+  };
 }
 
 /**

package/src/hooks/handler.ts

@@ -41,6 +41,8 @@ import { resolveTranscriptPath } from "./resolve-transcript-path";
 import { getInstanceId } from "../../lib/telemetry-id";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 import { readStdinPayload } from "./read-stdin";
+import { readActiveCloudManagedPolicies, type CloudManagedPolicyArtifact } from "./cloud-managed-policies";
+import { readActivePause, type ActivePause } from "./session-pause";
 
 /**
  * Canonicalize an event name to PascalCase. Codex sends snake_case event names
@@ -134,6 +136,37 @@ export interface EvaluateHookEventOptions {
   fallbackCwd?: string;
 }
 
+/**
+ * Runs an observe-mode policy under the same timeout and error handling as an
+ * enforcing one, so what gets measured is what would actually have happened —
+ * including a policy that times out, which in enforce mode is an allow and must
+ * be recorded as one rather than as a would-deny.
+ */
+async function runObserved(
+  hook: CustomHook,
+  ctx: Parameters<CustomHook["fn"]>[0],
+  hookName: string,
+  eventType: string,
+  cli: IntegrationType,
+): Promise<PolicyResult> {
+  try {
+    return await Promise.race([
+      hook.fn(ctx),
+      new Promise<PolicyResult>((_, reject) => setTimeout(() => reject(new Error("timeout")), 10_000)),
+    ]);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    void trackHookEvent(getInstanceId(), "custom_hook_error", {
+      hook_name: hookName,
+      error_type: msg === "timeout" ? "timeout" : "exception",
+      event_type: eventType,
+      cli,
+      is_observe_mode: true,
+    });
+    return { decision: "allow" };
+  }
+}
+
 /**
  * The core hook-evaluation logic, decoupled from process stdin/stdout so it
  * can be called repeatedly inside a long-lived process (the daemon's warm
@@ -209,6 +242,20 @@ export async function evaluateHookEvent(
     let config: HooksConfig;
     let customHooksList: CustomHook[] = [];
     let conventionHookNames = new Set<string>();
+    let activePause: ActivePause | null = null;
+    /** Registered policy name → where it came from. See the set() below. */
+    const policyAttribution = new Map<
+      string,
+      { source: "custom" | "convention" | "cloud"; cloudPolicyId?: string; cloudRevision?: number }
+    >();
+    let cloudGeneration: number | undefined;
+    /** What observe-mode policies WOULD have done, had they been enforcing. */
+    const observedResults: Array<{
+      policyId: string;
+      revision: number;
+      decision: "deny" | "instruct";
+      reason: string | null;
+    }> = [];
 
     if (opts?.forceDecision) {
       // Fail-closed: no config/custom-hook loading at all — a daemon that
@@ -228,25 +275,80 @@ export async function evaluateHookEvent(
       // Load enabled policies (merge across project/local/global scopes)
       config = readMergedHooksConfig(session.cwd);
       clearPolicies();
-      registerBuiltinPolicies(config.enabledPolicies);
+
+      // A session pause suspends LOCAL policy only, for a bounded time. Cloud
+      // assignments are exempt below for the same reason `disabledCustomPolicies`
+      // already exempts them: a locally-issued command that could switch off a
+      // centrally assigned policy would make cloud enforcement decorative.
+      activePause = readActivePause(session.sessionId);
+      registerBuiltinPolicies(activePause ? [] : config.enabledPolicies);
+
+      // Cloud-managed policies are daemon-reconciled artifacts, but they use
+      // the same public JS policy API as local custom policies. Verify and add
+      // only the paths referenced by the atomically active generation.
+      const cloudManagedPolicies = readActiveCloudManagedPolicies();
+      // Recorded on every row once a machine is managed, whether or not a cloud
+      // policy decided this event: "what was deployed here at the time" is a
+      // separate question from "what decided", and only the former can tell a
+      // rollout that changed nothing from one that never reached the machine.
+      cloudGeneration = cloudManagedPolicies[0]?.generation;
+      const configuredCustomPaths = config.customPoliciesPaths ?? config.customPoliciesPath;
+      const allExplicitPaths =
+        cloudManagedPolicies.length === 0
+          ? configuredCustomPaths
+          : [
+              ...(typeof configuredCustomPaths === "string" ? [configuredCustomPaths] : configuredCustomPaths ?? []),
+              ...cloudManagedPolicies.map((policy) => policy.path),
+            ];
 
       // Load and register custom hooks (layer 2, after builtins)
-      const loadResult = await loadAllCustomHooks(config.customPoliciesPaths ?? config.customPoliciesPath, {
+      const loadResult = await loadAllCustomHooks(allExplicitPaths, {
         sessionCwd: session.cwd,
         customPoliciesEnabled: config.customPoliciesEnabled,
+        ...(cloudManagedPolicies.length > 0 ? { cloudManagedPolicies } : {}),
       });
       customHooksList = loadResult.hooks;
       const disabledCustomPolicies = new Set(config.disabledCustomPolicies ?? []);
       conventionHookNames = new Set(loadResult.conventionSources.flatMap((s) => s.hookNames));
 
       for (const hook of customHooksList) {
-        const policyId = (hook as CustomHook & { __policyId?: string }).__policyId;
-        if (policyId && disabledCustomPolicies.has(policyId)) continue;
+        const taggedHook = hook as CustomHook & {
+          __policyId?: string;
+          __cloudManaged?: CloudManagedPolicyArtifact;
+        };
+        const policyId = taggedHook.__policyId;
+        const cloudManaged = taggedHook.__cloudManaged;
+        // Local config cannot disable a centrally assigned policy merely by
+        // copying its generated ID into disabledCustomPolicies.
+        if (!cloudManaged && policyId && disabledCustomPolicies.has(policyId)) continue;
+        // Same rule for a session pause — it suspends local policy, never cloud.
+        if (!cloudManaged && activePause) continue;
         const hookName = hook.name;
         const conventionScope = (hook as CustomHook & { __conventionScope?: string }).__conventionScope;
         const isConvention = !!conventionScope;
-        const prefix = isConvention ? `.failproofai-${conventionScope}` : "custom";
+        const prefix = cloudManaged
+          ? `cloud/${cloudManaged.id}@${cloudManaged.revision}`
+          : isConvention
+            ? `.failproofai-${conventionScope}`
+            : "custom";
+        // Observe mode: run it for real, record what it decided, then hand back
+        // an allow. Evaluating and discarding is the whole point — a rollout is
+        // measured against real traffic before it can break anyone's work, and
+        // a policy that did not actually run would measure nothing.
+        const observeOnly = cloudManaged?.effect === "observe";
         const fn: PolicyFunction = async (ctx): Promise<PolicyResult> => {
+          if (observeOnly) {
+            const shadow = await runObserved(hook, ctx, hookName, eventType, cli);
+            if (shadow.decision !== "allow") {
+              observedResults.push({
+                policyId: cloudManaged!.id,
+                revision: cloudManaged!.revision,
+                decision: shadow.decision,
+                reason: shadow.reason ?? null,
+              });
+            }
+            return { decision: "allow" };
+          }
           try {
             const result = await Promise.race([
               hook.fn(ctx),
@@ -268,8 +370,18 @@ export async function evaluateHookEvent(
             return { decision: "allow" };
           }
         };
+        const registeredName = `${prefix}/${hookName}`;
+        // Record where this policy came from as structured data, keyed by the
+        // exact name the evaluator will report back. The display name already
+        // encodes it ("cloud/org-guard@7/…"), but only as a string — so the one
+        // question cloud attribution has to answer, "which rollout produced
+        // this decision", could only be answered by re-parsing our own label.
+        policyAttribution.set(registeredName, {
+          source: cloudManaged ? "cloud" : isConvention ? "convention" : "custom",
+          ...(cloudManaged ? { cloudPolicyId: cloudManaged.id, cloudRevision: cloudManaged.revision } : {}),
+        });
         registerPolicy(
-          `${prefix}/${hookName}`,
+          registeredName,
           hook.description ?? "",
           fn,
           hook.match ?? {},
@@ -335,6 +447,32 @@ export async function evaluateHookEvent(
       cwd: session.cwd,
       permissionMode: session.permissionMode,
       hookEventName: session.hookEventName,
+      // Attribution. A builtin is anything registered that is not in the map,
+      // so its absence is meaningful rather than missing — but only when a
+      // policy actually decided; a plain allow names nobody.
+      ...(result.policyName
+        ? (() => {
+            const attribution = policyAttribution.get(result.policyName);
+            return {
+              policySource: attribution?.source ?? ("builtin" as const),
+              ...(attribution?.cloudPolicyId ? { cloudPolicyId: attribution.cloudPolicyId } : {}),
+              ...(attribution?.cloudRevision !== undefined
+                ? { cloudRevision: attribution.cloudRevision }
+                : {}),
+            };
+          })()
+        : {}),
+      ...(cloudGeneration !== undefined ? { cloudGeneration } : {}),
+      // The point of observe mode is this record. Without it the rollout is
+      // unmeasurable and the row is indistinguishable from one where the policy
+      // never matched at all.
+      ...(observedResults.length > 0 ? { observed: observedResults } : {}),
+      // Without these, a row logged during a pause is indistinguishable from
+      // one where every policy ran and allowed — the log would assert a clean
+      // window over exactly the window that was not enforced.
+      ...(activePause
+        ? { pausedBy: activePause.setBy, pauseExpiresAt: activePause.expiresAt }
+        : {}),
     };
     try {
       persistHookActivity(activityEntry);