failproofai 1.0.0-beta.2 → 1.0.0-beta.21

package/src/hooks/hook-activity-store.ts

@@ -1,7 +1,7 @@
 /**
  * Disk persistence for hook activity entries using page-sized JSONL files.
  *
- * Storage location: ~/.failproofai/cache/hook-activity/
+ * Storage location: ~/.failproofai/hook-activity/ (see fp-home.ts)
  *
  * File structure:
  * - current.jsonl — actively written to, 0–PAGE_SIZE entries
@@ -22,19 +22,32 @@ import {
   unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
 import type { IntegrationType } from "./types";
+import { hookActivityDir } from "./fp-home";
 
 export const PAGE_SIZE = 25;
 
-const DEFAULT_STORE_DIR = join(homedir(), ".failproofai", "cache", "hook-activity");
+/**
+ * Layout 2 promoted this out of `cache/`. It was never a cache — nothing
+ * regenerates it, and deleting it loses the decision history the dashboard's
+ * activity tab is built on. Resolved lazily (not at module load) so
+ * FAILPROOFAI_HOME is honoured by tests and containers that set it after
+ * import.
+ */
+const defaultStoreDir = () => hookActivityDir();
 const CURRENT_FILE = "current.jsonl";
 const COUNT_FILE = "current.count"; // tracks line count; O(1) read/write vs rereading current.jsonl
 const STATS_FILE = "stats.json";
 const LOCK_FILE = "current.lock";  // advisory lock for concurrent hook processes
 const LOCK_STALE_MS = 2000;        // steal lock if older than 2 s (covers crashed processes)
 
-let storeDir = DEFAULT_STORE_DIR;
+let storeDirOverride: string | null = null;
+/**
+ * A getter, not a module-load constant: `FAILPROOFAI_HOME` is routinely set by
+ * a test or a container AFTER this module is imported, and a value captured at
+ * import time would silently point every write at the real home.
+ */
+const storeDirValue = () => storeDirOverride ?? defaultStoreDir();
 let rotateSeq = 0;
 
 // ── Types ──
@@ -69,6 +82,45 @@ export interface HookActivityEntry {
   cwd?: string;
   permissionMode?: string;
   hookEventName?: string;
+  /**
+   * Set only on events evaluated while a session pause was active. Absent on
+   * every ordinary row and on every row written before pausing existed, so —
+   * like `matchedPolicies` — consumers must treat `undefined` as "not paused"
+   * rather than rendering it as unknown.
+   */
+  pausedBy?: string;
+  /** Epoch ms the pause lifts. Present iff `pausedBy` is. */
+  pauseExpiresAt?: number;
+  /**
+   * Where the policy that DECIDED came from. Absent when nothing decided (a
+   * plain allow) and on rows written before this existed — so, like
+   * `matchedPolicies`, `undefined` means "unknown", not "builtin".
+   */
+  policySource?: "builtin" | "custom" | "convention" | "cloud";
+  /** Cloud policy id of the decider. Present only when `policySource` is "cloud". */
+  cloudPolicyId?: string;
+  /** Immutable version of that policy — the half of attribution that identifies WHICH version ran. */
+  cloudVersion?: number;
+  /**
+   * The cloud deployment active when this event was evaluated, recorded on
+   * every row of a managed machine regardless of what decided. "What was
+   * deployed here" is a different question from "what decided", and only this
+   * distinguishes a rollout that changed no outcomes from one that never
+   * arrived.
+   */
+  cloudDeployment?: number;
+  /**
+   * What observe-mode policies WOULD have done, had they been enforcing. This
+   * record is the entire point of observe mode: without it the row is
+   * indistinguishable from one where the policy never matched, and the rollout
+   * being trialled is unmeasurable.
+   */
+  observed?: Array<{
+    policyId: string;
+    version: number;
+    decision: "deny" | "instruct";
+    reason: string | null;
+  }>;
 }
 
 export interface HookActivityFilters {
@@ -77,6 +129,12 @@ export interface HookActivityFilters {
   policyName?: string;
   sessionId?: string;
   integration?: IntegrationType;
+  /**
+   * Filter by where the deciding policy came from. "Show me everything my
+   * organization's policies decided" is the question cloud rollout reporting
+   * is built on, and it is unanswerable without this.
+   */
+  source?: "builtin" | "custom" | "convention" | "cloud";
 }
 
 export interface HookActivityStats {
@@ -89,8 +147,8 @@ export interface HookActivityStats {
 // ── Directory setup ──
 
 function ensureDir(): void {
-  if (!existsSync(storeDir)) {
-    mkdirSync(storeDir, { recursive: true });
+  if (!existsSync(storeDirValue())) {
+    mkdirSync(storeDirValue(), { recursive: true });
   }
 }
 
@@ -98,7 +156,7 @@ function ensureDir(): void {
 
 function acquireLock(): void {
   ensureDir();
-  const lockPath = join(storeDir, LOCK_FILE);
+  const lockPath = join(storeDirValue(), LOCK_FILE);
   const deadline = Date.now() + LOCK_STALE_MS;
   while (Date.now() < deadline) {
     try {
@@ -121,7 +179,7 @@ function acquireLock(): void {
 }
 
 function releaseLock(): void {
-  try { unlinkSync(join(storeDir, LOCK_FILE)); } catch { /* ignore */ }
+  try { unlinkSync(join(storeDirValue(), LOCK_FILE)); } catch { /* ignore */ }
 }
 
 // ── Writing (synchronous — hook handler is short-lived) ──
@@ -130,8 +188,8 @@ export function persistHookActivity(entry: HookActivityEntry): void {
   ensureDir();
   acquireLock();
   try {
-    const currentPath = join(storeDir, CURRENT_FILE);
-    const countPath = join(storeDir, COUNT_FILE);
+    const currentPath = join(storeDirValue(), CURRENT_FILE);
+    const countPath = join(storeDirValue(), COUNT_FILE);
 
     const lineCount = readCount(countPath);
     if (lineCount >= PAGE_SIZE) {
@@ -153,7 +211,7 @@ export function persistHookActivity(entry: HookActivityEntry): void {
 
 function rotate(currentPath: string, countPath: string): void {
   const archiveName = `page-${Date.now()}-${rotateSeq++}.jsonl`;
-  const archivePath = join(storeDir, archiveName);
+  const archivePath = join(storeDirValue(), archiveName);
   renameSync(currentPath, archivePath);
   // Reset count for the fresh file (write 0 — next append will set it to 1)
   writeCount(countPath, 0);
@@ -195,14 +253,21 @@ interface StoredStats {
 
 function readStoredStats(): StoredStats {
   try {
-    return JSON.parse(readFileSync(join(storeDir, STATS_FILE), "utf-8")) as StoredStats;
+    return JSON.parse(readFileSync(join(storeDirValue(), STATS_FILE), "utf-8")) as StoredStats;
   } catch {
     return { totalEvents: 0, denyCount: 0, policyMap: {} };
   }
 }
 
-function updateStats(entry: HookActivityEntry): void {
-  const s = readStoredStats();
+/**
+ * Fold one entry into a running total, in place.
+ *
+ * Extracted so the incremental path and {@link rebuildHookActivityStats} cannot
+ * disagree: a rebuild that counted differently from the appends would produce
+ * numbers that silently drift from the log they claim to summarise, and nothing
+ * would catch it because both sides look plausible on their own.
+ */
+function foldEntry(s: StoredStats, entry: HookActivityEntry): void {
   s.totalEvents += 1;
   if (entry.decision === "deny") s.denyCount += 1;
   if (entry.policyNames && entry.policyNames.length > 0) {
@@ -212,17 +277,64 @@ function updateStats(entry: HookActivityEntry): void {
   } else if (entry.policyName) {
     s.policyMap[entry.policyName] = (s.policyMap[entry.policyName] ?? 0) + 1;
   }
-  // Write atomically: write to a PID-unique temp file then rename — prevents partial reads.
-  const tmpPath = join(storeDir, `stats.json.${process.pid}.tmp`);
+}
+
+/** Write stats atomically: PID-unique temp then rename, so no reader sees a partial file. */
+function writeStoredStats(s: StoredStats): boolean {
+  const tmpPath = join(storeDirValue(), `stats.json.${process.pid}.tmp`);
   try {
     writeFileSync(tmpPath, JSON.stringify(s), "utf-8");
-    renameSync(tmpPath, join(storeDir, STATS_FILE));
+    renameSync(tmpPath, join(storeDirValue(), STATS_FILE));
+    return true;
   } catch {
     try { unlinkSync(tmpPath); } catch { /* ignore */ }
     // Non-fatal: stats file write failure doesn't block the hook
+    return false;
   }
 }
 
+function updateStats(entry: HookActivityEntry): void {
+  const s = readStoredStats();
+  foldEntry(s, entry);
+  writeStoredStats(s);
+}
+
+/**
+ * Recompute `stats.json` from every page on disk.
+ *
+ * WHY THIS EXISTS. `stats.json` is INCREMENTAL — `updateStats` adds one entry per
+ * append and nothing ever rescans — so it is the only part of the decision log
+ * that cannot survive being lost. The layout migration carries the pages (real
+ * records) and deliberately drops `stats.json` and `current.count` as derived
+ * state, on the stated grounds that "the store rebuilds them". It did not: there
+ * was no rebuild anywhere in the store, so `readStoredStats()` fell through its
+ * catch to zeroes and began re-accumulating from the next event. A user upgrading
+ * from a pre-daemon home kept every record and lost every total — the dashboard
+ * listed their history while reporting 0 events, 0 denies and no top policy.
+ *
+ * It is exactly recomputable, which is what makes dropping it the right call and
+ * this function the missing half: pages are never pruned (there is no retention
+ * anywhere in this module), so the files on disk ARE the whole history.
+ *
+ * Returns the totals it wrote, or null if there was nothing to read.
+ */
+export function rebuildHookActivityStats(): StoredStats | null {
+  ensureDir();
+  const files = [CURRENT_FILE, ...getArchiveFiles()];
+  const s: StoredStats = { totalEvents: 0, denyCount: 0, policyMap: {} };
+  let sawAny = false;
+  for (const file of files) {
+    const path = join(storeDirValue(), file);
+    if (!existsSync(path)) continue;
+    sawAny = true;
+    // `readJsonlFile` already skips malformed lines, so a truncated tail costs
+    // that line rather than the whole rebuild.
+    for (const entry of readJsonlFile(path)) foldEntry(s, entry);
+  }
+  if (!sawAny) return null;
+  return writeStoredStats(s) ? s : null;
+}
+
 function readStats(): HookActivityStats {
   const s = readStoredStats();
   let topPolicy: string | null = null;
@@ -243,7 +355,7 @@ export function getHookActivityPage(page: number): HookActivityEntry[] {
   if (page < 1) return [];
 
   if (page === 1) {
-    const currentPath = join(storeDir, CURRENT_FILE);
+    const currentPath = join(storeDirValue(), CURRENT_FILE);
     return readJsonlFile(currentPath).reverse();
   }
 
@@ -251,7 +363,7 @@ export function getHookActivityPage(page: number): HookActivityEntry[] {
   const archiveIndex = page - 2;
   if (archiveIndex >= archives.length) return [];
 
-  return readJsonlFile(join(storeDir, archives[archiveIndex])).reverse();
+  return readJsonlFile(join(storeDirValue(), archives[archiveIndex])).reverse();
 }
 
 export function getHookActivityPageCount(): number {
@@ -262,13 +374,13 @@ export function getHookActivityPageCount(): number {
 export function getAllHookActivityEntries(): HookActivityEntry[] {
   ensureDir();
 
-  const currentPath = join(storeDir, CURRENT_FILE);
+  const currentPath = join(storeDirValue(), CURRENT_FILE);
   const currentEntries = readJsonlFile(currentPath).reverse();
 
   const archives = getArchiveFiles();
   const archiveEntries: HookActivityEntry[] = [];
   for (const file of archives) {
-    const entries = readJsonlFile(join(storeDir, file));
+    const entries = readJsonlFile(join(storeDirValue(), file));
     archiveEntries.push(...entries.reverse());
   }
 
@@ -298,6 +410,11 @@ export function searchHookActivity(
       return false;
     }
     if (filters.integration && entry.integration !== filters.integration) return false;
+    // Rows written before attribution existed have no policySource. They are
+    // excluded from every source filter rather than guessed at — a wrong
+    // attribution is worse than a missing one when the point is proving which
+    // rollout decided something.
+    if (filters.source && entry.policySource !== filters.source) return false;
     return true;
   });
 
@@ -325,6 +442,34 @@ export function getHookActivityHistory(page: number): {
 
 // ── Internal helpers ──
 
+/**
+ * Accept the pre-rename spelling of the two cloud-attribution fields.
+ *
+ * These pages are written by the DAEMON, so a machine that was cloud-connected
+ * before `cloudRevision`→`cloudVersion` / `cloudGeneration`→`cloudDeployment` has
+ * real rows on disk naming the old keys. Nothing here validates the shape — the
+ * line is `JSON.parse`d and cast — so those rows do not error, they simply carry
+ * keys nothing reads: every pre-upgrade cloud-decided decision renders as
+ * unattributed, which is the exact question these fields were added to answer.
+ *
+ * The Rust writer takes the same two aliases (`transform.rs`). Renaming a symbol
+ * is safe; renaming the name of data an older build already wrote is not.
+ *
+ * One-directional and non-destructive: the new key wins if both somehow appear,
+ * and the old key is left in place rather than deleted, since nothing reads it and
+ * removing it would rewrite history to look like it was always current.
+ */
+function withRenamedCloudFields(raw: Record<string, unknown>): HookActivityEntry {
+  const entry = raw as HookActivityEntry & Record<string, unknown>;
+  if (entry.cloudVersion === undefined && typeof raw.cloudRevision === "number") {
+    entry.cloudVersion = raw.cloudRevision;
+  }
+  if (entry.cloudDeployment === undefined && typeof raw.cloudGeneration === "number") {
+    entry.cloudDeployment = raw.cloudGeneration;
+  }
+  return entry;
+}
+
 function readJsonlFile(filePath: string): HookActivityEntry[] {
   const content = readFileSafe(filePath);
   if (!content.trim()) return [];
@@ -332,7 +477,7 @@ function readJsonlFile(filePath: string): HookActivityEntry[] {
   const entries: HookActivityEntry[] = [];
   for (const line of content.trim().split("\n")) {
     try {
-      entries.push(JSON.parse(line) as HookActivityEntry);
+      entries.push(withRenamedCloudFields(JSON.parse(line) as Record<string, unknown>));
     } catch {
       // Skip malformed lines
     }
@@ -342,7 +487,7 @@ function readJsonlFile(filePath: string): HookActivityEntry[] {
 
 function getArchiveFiles(): string[] {
   try {
-    const files = readdirSync(storeDir);
+    const files = readdirSync(storeDirValue());
     return files
       .filter((f) => f.startsWith("page-") && f.endsWith(".jsonl"))
       .sort((a, b) => {
@@ -364,5 +509,7 @@ function getArchiveFiles(): string[] {
 
 export function _resetForTest(testDir?: string): void {
   rotateSeq = 0;
-  storeDir = testDir ?? DEFAULT_STORE_DIR;
+  // null, not the default path: clearing the override lets the getter re-read
+  // FAILPROOFAI_HOME, which a test may have changed since this module loaded.
+  storeDirOverride = testDir ?? null;
 }

package/src/hooks/hook-logger.ts

@@ -21,14 +21,14 @@ import {
   statSync,
 } from "node:fs";
 import { join } from "node:path";
-import { homedir } from "node:os";
+import { logsDir } from "./fp-home";
 
 export type LogLevel = "info" | "warn" | "error";
 
 const LEVEL_ORDER: Record<LogLevel, number> = { info: 0, warn: 1, error: 2 };
 const MAX_FILE_SIZE = 512 * 1024; // 500 KB
 const LOG_FILENAME = "hooks.log";
-const DEFAULT_LOG_DIR = join(homedir(), ".failproofai", "logs");
+const DEFAULT_LOG_DIR = logsDir();
 
 // ── State (lazy-initialized) ──
 

package/src/hooks/hook-telemetry.ts

@@ -7,6 +7,7 @@
 
 import { version } from "../../package.json";
 import { POSTHOG_API_KEY, POSTHOG_PRODUCT } from "../posthog-key";
+import { isTelemetryEnabled } from "../../lib/telemetry-enabled";
 
 const API_KEY = POSTHOG_API_KEY;
 const CAPTURE_URL = "https://us.i.posthog.com/capture/";
@@ -57,7 +58,10 @@ export async function trackHookEvent(
   event: string,
   properties?: Record<string, unknown>,
 ): Promise<void> {
-  if (process.env.FAILPROOFAI_TELEMETRY_DISABLED === "1") return;
+  // Honours the config file as well as the env var — the env var alone cannot
+  // reach a system-scope daemon. Memoised, so this stays off the hook path's
+  // latency budget. See lib/telemetry-enabled.ts.
+  if (!isTelemetryEnabled()) return;
 
   const p = sendEvent(distinctId, event, properties);
   pending.add(p);

package/src/hooks/hooks-config.ts

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import type { HooksConfig, ConventionPolicyRecord } from "./policy-types";
 import type { HookScope } from "./types";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
+import { globalPolicyConfigFile } from "./fp-home";
 
 /** Normalize plural and legacy singular explicit policy paths for consumers. */
 export function configuredCustomPolicyPaths(
@@ -69,7 +70,7 @@ export function readMergedHooksConfig(cwd?: string): HooksConfig {
   const base = findProjectConfigDir(cwd ?? process.cwd());
   const projectPath = resolve(base, ".failproofai", "policies-config.json");
   const localPath = resolve(base, ".failproofai", "policies-config.local.json");
-  const globalPath = resolve(homedir(), ".failproofai", "policies-config.json");
+  const globalPath = globalPolicyConfigFile();
 
   const project = readConfigAt(projectPath);
   const local = readConfigAt(localPath);
@@ -128,7 +129,7 @@ export function readMergedHooksConfig(cwd?: string): HooksConfig {
 }
 
 function getConfigPath(): string {
-  return resolve(homedir(), ".failproofai", "policies-config.json");
+  return globalPolicyConfigFile();
 }
 
 export function readHooksConfig(): HooksConfig {
@@ -160,7 +161,7 @@ export function writeHooksConfig(config: HooksConfig): void {
 export function getConfigPathForScope(scope: HookScope, cwd?: string): string {
   switch (scope) {
     case "user":
-      return resolve(homedir(), ".failproofai", "policies-config.json");
+      return globalPolicyConfigFile();
     case "project":
       return resolve(findProjectConfigDir(cwd ?? process.cwd()), ".failproofai", "policies-config.json");
     case "local":

package/src/hooks/integrations.ts

@@ -14,7 +14,6 @@ import { homedir } from "node:os";
 import { parseDocument, type Document } from "yaml";
 import { listHermesProfiles, hermesRoot } from "../../lib/hermes-profiles";
 import {
-  HOOK_EVENT_TYPES,
   CLAUDE_INSTALL_EVENT_TYPES,
   HOOK_SCOPES,
   CODEX_HOOK_EVENT_TYPES,

package/src/hooks/loader-utils.ts

@@ -11,12 +11,75 @@
  *
  * The ESM shim includes hooks API exports.
  */
-import { readFile, writeFile, unlink, access } from "fs/promises";
-import { resolve, dirname, relative } from "path";
+import { readFile, writeFile, unlink, access, mkdir, lstat } from "fs/promises";
+import { tmpdir } from "os";
+import { resolve, dirname, relative, join } from "path";
 import { pathToFileURL } from "url";
+import { createHash } from "crypto";
+import { shimsDir } from "./fp-home";
+import { hookLogWarn } from "./hook-logger";
 
 export const TMP_SUFFIX = ".__failproofai_tmp__.mjs";
 
+/**
+ * Anything this loader generated, by name.
+ *
+ * The temporary tree is written BESIDE the user's sources, because that is the
+ * only place a rewritten relative import still resolves. That was harmless
+ * while the name was fixed — an abnormally terminated hook left at most one
+ * stale file per source, overwritten on the next load — but the name now
+ * carries a pid and a sequence number, so every kill (a CLI hook timeout, a
+ * Ctrl-C) leaves a uniquely-named file behind forever.
+ *
+ * Two consequences, and the second is the visible one: the directory fills up,
+ * and `findSkippedPolicyFiles` reports each leftover back to the user as a
+ * policy file that will not load — an accusation about a file failproofai
+ * wrote itself.
+ */
+const TMP_ARTIFACT_RE = /\.__failproofai_tmp__\./;
+
+/** True for a file this loader generated rather than one the user wrote. */
+export function isTmpArtifact(name: string): boolean {
+  return TMP_ARTIFACT_RE.test(name);
+}
+
+/**
+ * How stale a generated file must be before a sweep will remove it.
+ *
+ * Another process may be mid-load right now, and its temporary tree is live
+ * until its `import()` resolves. Well past the 10s a module load is allowed,
+ * so a sweep can never delete a file another loader is still using.
+ */
+const TMP_SWEEP_MIN_AGE_MS = 60_000;
+
+/**
+ * Remove generated files left behind by a load that was killed.
+ *
+ * Best-effort and never throws: this runs on the hook path, and failing to
+ * tidy up is not worth failing an evaluation over.
+ */
+export async function sweepStaleTmpArtifacts(dir: string, now = Date.now()): Promise<number> {
+  let removed = 0;
+  try {
+    const { readdir, stat } = await import("fs/promises");
+    for (const name of await readdir(dir)) {
+      if (!isTmpArtifact(name)) continue;
+      const path = resolve(dir, name);
+      try {
+        const info = await stat(path);
+        if (now - info.mtimeMs < TMP_SWEEP_MIN_AGE_MS) continue;
+        await unlink(path);
+        removed++;
+      } catch {
+        /* raced with another sweep, or not ours to remove */
+      }
+    }
+  } catch {
+    /* unreadable directory — nothing to sweep */
+  }
+  return removed;
+}
+
 /** Regex to find local relative import specifiers (ESM). */
 const LOCAL_IMPORT_RE = /(?:import\s+(?:[\s\S]*?\s+from\s+)?|export\s+(?:[\s\S]*?\s+from\s+))(['"])(\.\.?\/[^'"]+)\1/g;
 
@@ -74,11 +137,57 @@ export async function resolveLocalImport(
  * Exports the full public API of failproofai: customPolicies, allow, deny, instruct,
  * getCustomHooks, clearCustomHooks.
  */
+/**
+ * Create the ESM shim that lets a policy file's `import ... from 'failproofai'`
+ * resolve, and return where it landed.
+ *
+ * NOT beside `dist/index.js`, which is where this used to go. That directory
+ * belongs to whoever installed the package, and on a system-wide install
+ * (`sudo npm i -g`, a container image, a shared build host, a CI runner) it is
+ * root-owned — so every non-root user running a hook failed with EACCES, the
+ * policy never loaded, and the hook exited 0. Builtins kept firing while
+ * cloud-managed and custom policies silently stopped, so the machine looked
+ * protected. That is the worst available failure for a policy engine.
+ *
+ * Two locations, and the ORDER OF OPERATIONS matters more than the choice:
+ *
+ *  1. `<home>/state/shims` — created at 0700 and owned by the user running the
+ *     hook. Unlike a shared `/tmp`, no other local user can pre-plant a file at
+ *     a path we are about to `import`.
+ *  2. `os.tmpdir()` — only when the first is unusable.
+ *
+ * **The write lives inside the same `try` as the mkdir on purpose.** `mkdir`
+ * with `recursive` RESOLVES on a directory that already exists, whatever its
+ * mode — so a `state/shims` left behind unwritable (a container that ran the
+ * CLI as root and then dropped to a non-root user; this very function creates
+ * that chain) would sail past a mkdir-only guard and throw EACCES on the write,
+ * reproducing the exact fail-open this function exists to fix. Any failure of
+ * either step falls through to the fallback, and says so — a silent slide into
+ * the weaker path is the same class of bug again.
+ */
+async function writeShim(
+  dir: string,
+  name: string,
+  code: string,
+  exclusive: boolean,
+): Promise<string> {
+  const shimPath = join(dir, name);
+  // 0600 explicitly: an unset mode is `0666 & ~umask`, and `umask 000` is
+  // routine in containers — which in the fallback means a world-writable file
+  // in shared /tmp that this process then imports.
+  await writeFile(shimPath, code, {
+    encoding: "utf-8",
+    mode: 0o600,
+    ...(exclusive ? { flag: "wx" as const } : {}),
+  });
+  return shimPath;
+}
+
 export async function createEsmShim(
-  distIndex: string,
+  _distIndex: string,
   distUrl: string,
+  tmpSuffix = TMP_SUFFIX,
 ): Promise<{ shimPath: string; shimUrl: string }> {
-  const shimPath = distIndex + ".__failproofai_esm_shim__.mjs";
   const shimCode = [
     `import _cjs from '${distUrl}';`,
     `export const customPolicies = _cjs.customPolicies;`,
@@ -89,7 +198,35 @@ export async function createEsmShim(
     `export const instruct = _cjs.instruct;`,
     `export default _cjs;`,
   ].join("\n");
-  await writeFile(shimPath, shimCode, "utf-8");
+  // The name still carries `tmpSuffix` (pid + load sequence + a random id).
+  // `fingerprintTemporaryTree` normalises exactly that substring away before
+  // hashing, so the policy module cache still hits; a name it could not
+  // normalise would force a cold module load on every single hook call.
+  const name = `failproofai-dist${tmpSuffix}.shim.mjs`;
+
+  try {
+    const dir = shimsDir();
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // `mkdir` accepts a pre-existing SYMLINK here and a plain write would
+    // follow it out of the home. Confirm we got a real directory we own,
+    // unreadable to anyone else, before writing something we are about to
+    // execute.
+    const st = await lstat(dir);
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    if (!st.isDirectory() || st.isSymbolicLink() || (uid !== null && st.uid !== uid) || st.mode & 0o077) {
+      throw new Error(`${dir} is not a private directory owned by this user`);
+    }
+    const shimPath = await writeShim(dir, name, shimCode, false);
+    return { shimPath, shimUrl: pathToFileURL(shimPath).href };
+  } catch (err) {
+    hookLogWarn(
+      `policy shim directory unusable (${err instanceof Error ? err.message : String(err)}); falling back to ${tmpdir()}`,
+    );
+  }
+
+  // Predictable name in a shared directory, so O_EXCL: refuse rather than write
+  // through something another user planted.
+  const shimPath = await writeShim(tmpdir(), name, shimCode, true);
   return { shimPath, shimUrl: pathToFileURL(shimPath).href };
 }
 
@@ -101,6 +238,17 @@ export async function rewriteFileTree(
   entryPath: string,
   distUrl: string | null,
   distIndex: string | null,
+  tmpSuffix = TMP_SUFFIX,
+  /**
+   * SHA-256 the ENTRY file's raw bytes must match, re-checked here at the moment
+   * they are read for rewriting and import. Cloud-managed policies pass their
+   * pinned digest so the bytes that get imported are the same bytes that were
+   * verified — closing a TOCTOU where an earlier caller hashed the file, then
+   * this function independently re-read it (a window in which a same-user
+   * attacker could swap the bytes so a verified file imports unverified code).
+   * Only the entry is content-addressed; transitive local imports are not.
+   */
+  entrySha256?: string | null,
 ): Promise<string[]> {
   const queue: string[] = [entryPath];
   const visited = new Set<string>();
@@ -108,7 +256,7 @@ export async function rewriteFileTree(
 
   let esmShimUrl: string | null = null;
   if (distIndex && distUrl) {
-    const shim = await createEsmShim(distIndex, distUrl);
+    const shim = await createEsmShim(distIndex, distUrl, tmpSuffix);
     tmpFiles.push(shim.shimPath);
     esmShimUrl = shim.shimUrl;
   }
@@ -118,7 +266,22 @@ export async function rewriteFileTree(
     if (visited.has(filePath)) continue;
     visited.add(filePath);
 
-    let code = await readFile(filePath, "utf-8");
+    let code: string;
+    if (entrySha256 && filePath === entryPath) {
+      // Read the raw bytes, verify the pin against THEM, then decode and rewrite
+      // that same in-memory content — filePath is never read again, so the bytes
+      // imported below are exactly the bytes verified here.
+      const buf = await readFile(filePath);
+      const actual = createHash("sha256").update(buf).digest("hex");
+      if (actual !== entrySha256) {
+        throw new Error(
+          `cloud-managed policy failed integrity re-verification at load: expected ${entrySha256}, got ${actual}`,
+        );
+      }
+      code = buf.toString("utf-8");
+    } else {
+      code = await readFile(filePath, "utf-8");
+    }
 
     // Rewrite 'failproofai' or legacy 'claudeye' imports to the ESM shim (or direct CJS for require)
     if (esmShimUrl) {
@@ -148,7 +311,7 @@ export async function rewriteFileTree(
         if (!visited.has(resolved) && !queue.includes(resolved)) {
           queue.push(resolved);
         }
-        let relPath = relative(dir, resolved + TMP_SUFFIX).split("\\").join("/");
+        let relPath = relative(dir, resolved + tmpSuffix).split("\\").join("/");
         if (!relPath.startsWith(".")) relPath = "./" + relPath;
         rewrites.set(specifier, relPath);
       }
@@ -163,7 +326,7 @@ export async function rewriteFileTree(
       code = code.replace(new RegExp(`"${escaped}"`, "g"), `"${replacement}"`);
     }
 
-    const tmpPath = filePath + TMP_SUFFIX;
+    const tmpPath = filePath + tmpSuffix;
     await writeFile(tmpPath, code, "utf-8");
     tmpFiles.push(tmpPath);
   }