failproofai 1.0.0-beta.2 → 1.0.0-beta.3

package/src/hooks/configure-wizard.ts

@@ -13,12 +13,13 @@
  * install/uninstall manager and the existing searchable policy picker.
  */
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { resolve, sep } from "node:path";
 
 import {
   selectOne,
   multiSelect,
+  promptText,
   intro,
   outro,
   summarize,
@@ -26,6 +27,12 @@ import {
   type TTYIn,
   type TTYOut,
 } from "./tui";
+import {
+  DEFAULT_INGEST_URL,
+  validateIngestKey,
+  writeIngestCredential,
+  writeCollectorSettings,
+} from "./collector-config";
 import {
   detectInstalledClis,
   getIntegration,
@@ -47,6 +54,12 @@ import {
   setDaemonConfigured,
 } from "./daemon-service";
 import { hookLogWarn } from "./hook-logger";
+import {
+  readCloudCredentials,
+  verifyCloudCredentials,
+  writeCloudCredentials,
+} from "./cloud-enrollment";
+import { cloudBaseFor, ingestUrlFor } from "./cloud-connection";
 
 export interface WizardIO {
   stdin?: TTYIn;
@@ -365,7 +378,14 @@ export function reviewLines(state: {
   const assistantNames = clis.map((c) => getIntegration(c).displayName);
   lines.push(`  Where      : ${where}`);
   lines.push(`  Assistants : ${assistantNames.length ? summarize(assistantNames, "assistants") : "(none)"}`);
-  lines.push(`  Policies   : ${policies.length} enabled`);
+  // Zero is a deliberate answer, not a failed step — say so, and say where to
+  // change it, so the review screen doesn't read like the wizard lost the
+  // selection. Hooks still install; only the builtin set is empty.
+  lines.push(
+    policies.length === 0
+      ? "  Policies   : none enabled (add later: failproofai policies --install)"
+      : `  Policies   : ${policies.length} enabled`,
+  );
   if (installDaemon && isDaemonSupportedPlatform()) {
     lines.push(
       `  Daemon     : failproofaid, installed as a system service running as you`,
@@ -635,12 +655,23 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
   const presetChoices = buildPresetChoices(cwd, customEnabledBefore);
   const hasCustomFiles = describeCustomPolicies(cwd).fileCount > 0;
 
+  // No minimum. Ticking nothing is a real answer — someone who only wants their
+  // own custom policies, or who intends to pick bundles later from the
+  // dashboard, was previously stuck on this step with no way forward and no
+  // explanation beyond "Select at least 1". An empty set is already supported
+  // end to end: `installHooksImpl` documents its explicit-array path as "may be
+  // empty", `replace: true` makes it the full enabled set, and `summarize([])`
+  // renders "none". Hooks still install, so enforcement can be switched on
+  // later without re-running setup.
+  //
+  // The assistants step above keeps its minimum deliberately: an empty CLI list
+  // does NOT mean "no assistants" there — `installHooksImpl` falls back to
+  // ["claude"], so letting it through would silently install for Claude.
   const presets = await multiSelect<string>({
     message: "What should we guard against?",
     choices: presetChoices,
-    minSelected: 1,
     summaryNoun: "bundles",
-    hint: "space toggles · combine presets · ↵ confirm",
+    hint: "space toggles · combine presets · ↵ confirm · none is fine",
     stdin,
     stdout,
   });
@@ -650,7 +681,166 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
   // locked-unchecked and must not write a disabling flag.
   const customEnabled = hasCustomFiles ? presets.includes(CUSTOM) : undefined;
 
-  // 4 — Review & apply
+  // 4 — Send data to AgentEye? Last, and only when a daemon was asked for,
+  // since the daemon is what runs the collector.
+  //
+  // Deliberately AFTER the enforcement questions rather than beside the daemon
+  // one: by this point the user has decided what to protect, so "and would you
+  // like to see it in a dashboard?" follows naturally, where asking up front
+  // interrupts setup with a question about a product they may not have.
+  //
+  // Defaults to NO, and the transcript choice is a SEPARATE question from the
+  // key, because a transcript carries prompts, file contents and whatever was
+  // pasted into a terminal. Configuring ingest must never silently send those.
+  let collector: { cred: { url: string; key: string }; sessions: boolean } | null = null;
+  if (daemonWanted) {
+    const send = await selectOne<"yes" | "no">({
+      message: "Send session and hook data to AgentEye?",
+      choices: [
+        {
+          label: "Not now",
+          value: "no",
+          hint: "nothing leaves this machine",
+        },
+        {
+          label: "Yes — connect to a dashboard",
+          value: "yes",
+          hint: "needs an events:add API key",
+        },
+      ],
+      stdin,
+      stdout,
+    });
+    if (send === null) return cancel();
+
+    if (send === "yes") {
+      // If this machine is ALREADY enrolled with Failproof Cloud, it has a URL
+      // and a token that usually work for both capabilities. Asking for them
+      // again is the seam that made connecting feel like two products: someone
+      // runs `--connect`, sees an empty dashboard, and has no reason to think a
+      // second credential exists. Offer what we already know, and let it be
+      // overridden.
+      const existing = readCloudCredentials();
+      let url: string | null = null;
+      let key: string | null = null;
+
+      if (existing) {
+        const reuse = await selectOne<"reuse" | "other">({
+          message: `Use this machine's existing connection to ${existing.url}?`,
+          choices: [
+            {
+              label: `Yes — reuse it`,
+              value: "reuse",
+              hint: `as ${existing.machineId}, same token`,
+            },
+            { label: "No — use a different endpoint and key", value: "other", hint: "" },
+          ],
+          stdin,
+          stdout,
+        });
+        if (reuse === null) return cancel();
+        if (reuse === "reuse") {
+          url = ingestUrlFor(existing.url);
+          key = existing.token;
+        }
+      }
+
+      if (url === null) {
+        const entered = await promptText({
+          message: "Failproof Cloud URL",
+          defaultValue: cloudBaseFor(DEFAULT_INGEST_URL),
+          hint: "Enter for the hosted endpoint",
+          validate: (v) => (/^https?:\/\//.test(v) ? null : "must be an http(s) URL"),
+          stdin,
+          stdout,
+        });
+        if (entered === null) return cancel();
+        // Asked for as a base and derived, so this and `--connect` take the
+        // same thing. Someone pasting the older `/events` endpoint still works.
+        url = ingestUrlFor(cloudBaseFor(entered));
+      }
+
+      if (key === null) {
+        key = await promptText({
+          message: "API key",
+          hint: "needs events:add",
+          // Masked: setup is routinely run while screen-sharing, and a pasted key
+          // would otherwise sit in the scrollback of every recording.
+          mask: true,
+          validate: (v) => (v.length >= 8 ? null : "that looks too short to be a key"),
+          stdin,
+          stdout,
+        });
+        if (key === null) return cancel();
+      }
+
+      // Check BEFORE writing anything. A typo'd key is otherwise only
+      // discovered later as a silent pile of 401s parked in failed/, which
+      // reads like a server problem rather than a typo.
+      stdout.write("\nChecking the key… ");
+      const check = await validateIngestKey({ url, key });
+      if (!check.ok) {
+        stdout.write(`\nThat did not work: ${check.reason}\n`);
+        const retry = await selectOne<"skip" | "anyway">({
+          message: "Carry on without sending data?",
+          choices: [
+            { label: "Yes, skip it", value: "skip", hint: "re-run failproofai config later" },
+            { label: "Save it anyway", value: "anyway", hint: "if you know the server is just down" },
+          ],
+          stdin,
+          stdout,
+        });
+        if (retry === null) return cancel();
+        if (retry === "skip") {
+          stdout.write("Skipping data collection. Everything else still applies.\n\n");
+        } else {
+          collector = { cred: { url, key }, sessions: false };
+        }
+      } else {
+        stdout.write("looks good.\n");
+        const sessions = await selectOne<"hooks" | "both">({
+          message: "What should it send?",
+          choices: [
+            {
+              label: "Policy decisions only",
+              value: "hooks",
+              hint: "which hooks fired and what they decided \u00b7 no file contents",
+            },
+            {
+              label: "Decisions and full session transcripts",
+              value: "both",
+              hint: "includes prompts, file contents and command output",
+            },
+          ],
+          stdin,
+          stdout,
+        });
+        if (sessions === null) return cancel();
+        collector = { cred: { url, key }, sessions: sessions === "both" };
+
+        // The other half of the same connection. If this machine is not
+        // enrolled for policy and the key turns out to carry `policies:pull`,
+        // enrol it here rather than making the user discover a second command.
+        // Silent when the key lacks the permission — an events-only key is a
+        // perfectly reasonable thing to have, and a warning about a capability
+        // nobody asked for is noise.
+        if (!readCloudCredentials()) {
+          const base = cloudBaseFor(url);
+          const machineId = hostname();
+          const enrol = await verifyCloudCredentials({ url: base, machineId, token: key });
+          if (enrol.ok) {
+            writeCloudCredentials({ url: base, machineId, token: key });
+            stdout.write(
+              `Also connected for cloud-managed policy (${enrol.policyCount} assigned, generation ${enrol.generation}).\n`,
+            );
+          }
+        }
+      }
+    }
+  }
+
+
+  // 5 — Review & apply
   const decision = await selectOne<"apply" | "cancel">({
     message: "Ready to apply?",
     body: reviewLines({ scope, clis, policies, cwd, customEnabled, installDaemon: daemonWanted }),
@@ -717,6 +907,32 @@ export async function runConfigureWizard(io: WizardIO = {}): Promise<WizardResul
     });
   }
 
+  // Collector config, written only when the daemon actually came up: the
+  // daemon is what runs the collector, so writing a credential for a service
+  // that failed to install would leave a key on disk doing nothing.
+  if (collector && daemonInstalled) {
+    try {
+      writeIngestCredential(collector.cred);
+      writeCollectorSettings({
+        sessions: collector.sessions,
+        hooks: true,
+        hooksVerbosity: "decisions",
+        redact: "minimal",
+      });
+      // Never the key, the URL, or the count — only that it happened and what
+      // shape of data the user agreed to send.
+      void emit("configure_collector", { sessions: collector.sessions });
+    } catch (err) {
+      // Non-fatal, like the daemon: the rest of setup is worth keeping, and a
+      // machine with no collector behaves exactly as every release before this.
+      hookLogWarn(
+        `collector configuration was not written: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  } else if (collector && !daemonInstalled) {
+    hookLogWarn("skipped collector configuration because the daemon was not installed");
+  }
+
   await applied;
   // Only now — a completed apply — is the launcher considered "seen", so the
   // first-run bare invocation stops redirecting here and opens the dashboard.

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/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);