failproofai 1.0.1 → 1.0.2-beta.1

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

@@ -31,6 +31,7 @@ import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId } from "../../lib/telemetry-id";
 import type { CustomHook } from "./policy-types";
 import type { CloudManagedPolicyArtifact } from "./cloud-managed-policies";
+import type { ResolvedPack } from "./pack-manifest";
 import { customPoliciesDir, shimsDir } from "./fp-home";
 
 const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
@@ -172,6 +173,11 @@ async function importWithDeadline(fileUrl: string): Promise<void> {
  * Load a single policy file into the globalThis custom hooks registry.
  * Does NOT clear the registry — caller is responsible for that.
  */
+export interface PolicyLoadFailure {
+  type: "module_not_found" | "syntax_error" | "load_timeout" | "runtime_error" | "path_missing";
+  reason: string;
+}
+
 async function loadSingleFile(
   absPath: string,
   opts?: {
@@ -180,7 +186,7 @@ async function loadSingleFile(
     /** Cloud-managed policies pass their pinned digest for load-time re-verification. */
     verifyEntrySha?: string;
   },
-): Promise<void> {
+): Promise<PolicyLoadFailure | null> {
   const g = globalThis as Record<string, unknown>;
   g[LOADING_KEY] = true;
 
@@ -208,7 +214,7 @@ async function loadSingleFile(
     const cached = policyModuleCache.get(absPath);
     if (cached?.fingerprint === fingerprint) {
       for (const hook of cached.hooks) customPolicies.add({ ...hook });
-      return;
+      return null;
     }
 
     const entryTmp = absPath + tmpSuffix;
@@ -222,6 +228,7 @@ async function loadSingleFile(
         .slice(hooksBefore)
         .map((hook) => ({ ...hook })),
     });
+    return null;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     const errorType = /Cannot find module|MODULE_NOT_FOUND|ENOENT/i.test(msg)
@@ -239,6 +246,7 @@ async function loadSingleFile(
     });
     if (opts?.strict) throw new Error(`Failed to load custom hooks from ${absPath}: ${msg}`);
     hookLogError(`failed to load custom hooks from ${absPath}: ${msg}`);
+    return { type: errorType, reason: msg };
   } finally {
     g[LOADING_KEY] = false;
     await cleanupTmpFiles(tmpFiles);
@@ -293,6 +301,8 @@ export interface ConventionSource {
 export interface LoadAllResult {
   hooks: CustomHook[];
   conventionSources: ConventionSource[];
+  /** Import failures keyed by pack id, including artifacts that registered no hooks. */
+  packFailures: Map<string, PolicyLoadFailure>;
 }
 
 export function customPolicyId(file: string, name: string): string {
@@ -330,17 +340,53 @@ function warnSkippedPolicyFiles(dir: string, scope: "project" | "user"): void {
   );
 }
 
+/**
+ * A pack's manifest declares what it contains; its artifact decides what runs.
+ * Nothing binds the two, so they can disagree — and the disagreement is silent
+ * in both directions and worse in one.
+ *
+ * A policy the artifact registers but the manifest omits is enforcement that no
+ * `failproofai policies` listing will ever show. A policy the manifest declares
+ * but the artifact never registers is the dangerous one: the listing says the
+ * machine is protected against something nothing is checking.
+ *
+ * Both are announced rather than corrected. The artifact is digest-pinned, so
+ * what it registers IS what the publisher shipped and dropping any of it would
+ * be inventing a third answer; the manifest is what needs fixing, upstream.
+ */
+function reconcilePackManifest(pack: ResolvedPack | undefined, loaded: CustomHook[]): void {
+  if (!pack || pack.policies.length === 0) return;
+  const declared = new Set(pack.policies.map((p) => p.name));
+  const registered = new Set(loaded.map((h) => h.name));
+  const missing = [...declared].filter((n) => !registered.has(n));
+  const extra = [...registered].filter((n) => !declared.has(n));
+  if (missing.length > 0) {
+    hookLogWarn(
+      `pack ${pack.id}@${pack.version} declares ${missing.join(", ")} but its artifact does not ` +
+        `register ${missing.length === 1 ? "it" : "them"} — listed as protection that never runs`,
+    );
+  }
+  if (extra.length > 0) {
+    hookLogWarn(
+      `pack ${pack.id}@${pack.version} registers undeclared ${extra.join(", ")} — ` +
+        `${extra.length === 1 ? "it enforces" : "they enforce"} but will not appear in listings`,
+    );
+  }
+}
+
 export async function loadAllCustomHooks(
   customPoliciesPaths: string | string[] | undefined,
   opts?: {
     sessionCwd?: string;
     customPoliciesEnabled?: boolean;
     cloudManagedPolicies?: CloudManagedPolicyArtifact[];
+    packs?: ResolvedPack[];
   },
 ): Promise<LoadAllResult> {
   clearCustomHooks();
 
   const conventionSources: ConventionSource[] = [];
+  const packFailures = new Map<string, PolicyLoadFailure>();
 
   const projectRoot = findProjectConfigDir(opts?.sessionCwd ?? process.cwd());
 
@@ -395,6 +441,30 @@ export async function loadAllCustomHooks(
     }
   }
 
+  // Installed packs, keyed by artifact path — the same content-addressing, and
+  // therefore the same collision, as the cloud map above: two packs whose entry
+  // file is byte-identical resolve to ONE artifact, `loadedPaths` imports it
+  // once, and the loser would vanish silently with its effect deciding nothing.
+  // Resolved the same way and for the same reason — toward ENFORCEMENT, because
+  // over-enforcing is visible to whoever hits it and under-enforcing is the
+  // silent failure — and announced, so an operator can act on it.
+  const packByPath = new Map<string, ResolvedPack>();
+  for (const pack of opts?.packs ?? []) {
+    const key = resolve(pack.path);
+    const existing = packByPath.get(key);
+    if (!existing) {
+      packByPath.set(key, pack);
+      continue;
+    }
+    hookLogWarn(
+      `packs ${existing.id} and ${pack.id} have identical source, so they share one artifact ` +
+        `and load as one pack; enforcing it if either asks to enforce`,
+    );
+    if (existing.effect !== "enforce" && pack.effect === "enforce") {
+      packByPath.set(key, pack);
+    }
+  }
+
   // 1. Explicit custom policy paths. Accept a string for callers/configs using
   // the legacy singular form.
   for (const customPoliciesPath of typeof customPoliciesPaths === "string"
@@ -403,31 +473,44 @@ export async function loadAllCustomHooks(
     // resolve() also normalizes absolute paths, so aliases containing `.` or
     // `..` share a dedup key with convention-discovered canonical paths.
     const absPath = resolve(projectRoot, customPoliciesPath);
+    const cloudManaged = cloudManagedByPath.get(absPath);
+    const pack = packByPath.get(absPath);
     if (existsSync(absPath)) {
       if (!loadedPaths.has(absPath)) {
         loadedPaths.add(absPath);
         const hooksBefore = getCustomHooks().length;
         // A cloud-managed policy re-verifies its pinned digest at load, binding
         // the imported bytes to what desired-state promised.
-        await loadSingleFile(absPath, {
-          verifyEntrySha: cloudManagedByPath.get(absPath)?.sha256,
+        // A pack re-verifies its pinned digest at load for the same reason a
+        // cloud policy does: the manifest read and the import are two moments,
+        // and only this one binds the bytes actually executed to what was
+        // promised.
+        const failure = await loadSingleFile(absPath, {
+          verifyEntrySha:
+            cloudManaged?.sha256 ?? pack?.sha256,
         });
+        if (failure && pack) packFailures.set(pack.id, failure);
         for (const hook of getCustomHooks().slice(hooksBefore)) {
-          const cloudManaged = cloudManagedByPath.get(absPath);
           const tagged = hook as CustomHook & {
             __policyId?: string;
             __cloudManaged?: CloudManagedPolicyArtifact;
+            __pack?: ResolvedPack;
           };
           if (cloudManaged) {
             tagged.__cloudManaged = cloudManaged;
             tagged.__policyId = `cloud:${cloudManaged.id}@${cloudManaged.version}:${hook.name}`;
+          } else if (pack) {
+            tagged.__pack = pack;
+            tagged.__policyId = `pack:${pack.id}@${pack.version}:${hook.name}`;
           } else {
             tagged.__policyId = customPolicyId(absPath, hook.name);
           }
         }
+        reconcilePackManifest(pack, getCustomHooks().slice(hooksBefore));
       }
     } else {
       hookLogWarn(`custom policy path not found: ${absPath}`);
+      if (pack) packFailures.set(pack.id, { type: "path_missing", reason: `path missing: ${absPath}` });
     }
   }
 
@@ -569,5 +652,5 @@ export async function loadAllCustomHooks(
     }
   }
 
-  return { hooks: allHooks, conventionSources };
+  return { hooks: allHooks, conventionSources, packFailures };
 }

package/src/hooks/fp-home.ts

@@ -210,6 +210,26 @@ export const globalPolicyConfigFile = (home?: string) =>
  */
 export const cloudPoliciesDir = (home?: string) => resolve(policiesDir(home), "cloud-policies");
 
+/**
+ * Installed policy packs — a sibling of `cloudPoliciesDir` and flat for the same
+ * reason: `artifacts/<sha256>.mjs` is content-addressed, so an install can only
+ * ever write a file that does not exist yet and is structurally incapable of
+ * disturbing what is currently live. `installed.json` names which artifacts are
+ * active and is written last, so activation is one atomic flip.
+ *
+ * Living under `policies/` is safe ONLY because the convention loader does not
+ * recurse — `discoverPolicyFiles` and `findSkippedPolicyFiles` both filter on
+ * `isFile()`, so nothing under `packs/` can be picked up as an unverified
+ * convention policy. `fp-home.test.ts` pins that non-recursion.
+ */
+export const packsDir = (home?: string) => resolve(policiesDir(home), "packs");
+
+/** The activation pointer. Written last and atomically. */
+export const packsInstalledFile = (home?: string) => resolve(packsDir(home), "installed.json");
+
+/** Content-addressed pack artifacts, shared across packs and versions. */
+export const packArtifactsDir = (home?: string) => resolve(packsDir(home), "artifacts");
+
 // ── Collector ────────────────────────────────────────────────────────────────
 
 /** Per-source watermarks. One directory per source — never shared: the cursor
@@ -218,7 +238,14 @@ export const cloudPoliciesDir = (home?: string) => resolve(policiesDir(home), "c
 export const cursorsDir = (source?: string, home?: string) =>
   source ? resolve(atHome(home, "cursors"), source) : atHome(home, "cursors");
 
-/** The SDK spool root. Mirrors `~/.agenteye/`, which stays supported. */
+/** The SDK spool root, and the ONLY root `failproofai-sdk` writes to.
+ *
+ *  The daemon additionally watches `~/.agenteye/events` (see `spool_dirs` in
+ *  `crates/fpai-collect/src/config.rs`) so that SDKs old enough to write there,
+ *  and batches already sitting there, keep being collected. But no current SDK
+ *  puts anything in it: `$AGENTEYE_HOME` used to redirect the spool and no
+ *  longer does, precisely so that exporting it for the older
+ *  `agenteye-collector` cannot relocate the SDK as a side effect. */
 export const customAgentsDir = (home?: string) => atHome(home, "custom-agents");
 export const customAgentsEventsDir = (home?: string) => resolve(customAgentsDir(home), "events");
 export const customAgentsFailedDir = (home?: string) => resolve(customAgentsDir(home), "failed");
@@ -273,6 +300,48 @@ export const auditSessionFile = (home?: string) => resolve(auditDir(home), "sess
 export const auditMachineFile = (home?: string) => resolve(auditDir(home), "machine.json");
 
 
+// ── fp-cloud-cli ───────────────────────────────────────────────────────────────────
+
+/**
+ * The Cloud CLI's own directory (`fp-cloud-cli` on PyPI, command `fp`).
+ *
+ * Written by PYTHON, not by anything in this repo's TypeScript or Rust — the
+ * CLI resolves it independently in `fp-cloud-cli/fp_cli/config.py`. It is declared
+ * here anyway because this file is the register of what may exist in the home,
+ * and a path absent from it is only safe by accident: `resettablePaths()` is a
+ * filter over `HOME_CLASSES`, so an unregistered directory survives today and
+ * survives the next migration only until someone lists its parent.
+ *
+ * Not classified itself — `auditDir`'s rule applies, classify the children. The
+ * directory may grow a cache later; the credential in it must never be dropped.
+ */
+export const fpcliDir = (home?: string) => atHome(home, "fpcli");
+
+/**
+ * The CLI's signed-in session. `0600`, written only by `fp login` / `fp logout`.
+ *
+ * Was `~/.fp/cli.json` — a third top-level dotfile for one product. The old
+ * file is deliberately left where it is: `load_config` in
+ * `fp-cloud-cli/fp_cli/config.py` reads it when nothing is here yet, writes the
+ * session to this path, and does NOT delete the original, so downgrading to a
+ * previous `fp` finds its session intact. Adoption is best-effort — an
+ * unwritable home hands back the session it found rather than logging the
+ * machine out — and it costs the user no login.
+ *
+ * This paragraph said the opposite until it was checked against the code: that
+ * there was no migration and the upgrade cost a login. There is one, it is
+ * covered by `fp-cloud-cli/tests/test_failproofai_home.py`, and the only true half
+ * was that the old file survives.
+ *
+ * `user-typed` for the same reason as `auditSessionFile` beside it: nothing
+ * regenerates a session, and dropping it silently signs the machine out.
+ *
+ * TS-side only, like `auditSessionFile`, and absent from `paths.rs` by design —
+ * the daemon has no reason to open a human credential, and mirroring a path
+ * only Python writes would give `paths.rs` an entry nothing there reads.
+ */
+export const fpcliAuthFile = (home?: string) => resolve(fpcliDir(home), "cli-auth.json");
+
 // ── Hook activity ────────────────────────────────────────────────────────────
 
 /** The decision log: page-sized JSONL the dashboard's activity tab reads. */
@@ -469,9 +538,15 @@ export type DataClass =
  *    else under it is scratch. Listing the parent is exactly how a reset came
  *    to delete undelivered events and the machine's own telemetry identity.
  *
- * `home-classification.test.ts` asserts every exported path function in this
- * module is either classified here or covered by a classified parent, so the
- * next path added to the home cannot skip the one question that matters.
+ * `__tests__/hooks/fp-home.test.ts` asserts every exported path function in
+ * this module is either classified here or covered by a classified parent, so
+ * the next path added to the home cannot skip the one question that matters.
+ *
+ * It cited `home-classification.test.ts` until that was checked — a file that
+ * has never existed. The guard was real and in the wrong place, which is the
+ * failure this header already describes happening once before: a citation is
+ * only load-bearing if somebody follows it, and the person who does is looking
+ * for the rule they are about to break.
  */
 export const HOME_CLASSES: readonly { path: (home?: string) => string; class: DataClass }[] = [
   // ── Never deleted: a person typed it ──
@@ -498,6 +573,11 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // with no notice, and the machine only finds out the next time it tries to
   // report.
   { path: auditSessionFile, class: "user-typed" },
+  // The Cloud CLI's session, written by Python (`fp-cloud-cli/fp_cli/config.py`). The
+  // one entry here whose writer is outside this repo's TS and Rust, which is
+  // exactly why it needs listing: nothing in a migration would otherwise know a
+  // credential lives under `fpcli/`.
+  { path: fpcliAuthFile, class: "user-typed" },
 
   // ── Never deleted: recorded and not yet shipped ──
   // Batches read out of transcripts and queued for upload. The reason losing
@@ -574,6 +654,14 @@ export const HOME_CLASSES: readonly { path: (home?: string) => string; class: Da
   // directory holds both the files a person wrote and the ones the fleet sent,
   // and only the second kind may be thrown away.
   { path: cloudPoliciesDir, class: "refetchable" },
+  // Installed packs. Third-party packs are re-fetchable by `failproofai pack
+  // add`; the bundled default pack is restored from the package immediately
+  // after reset. So this is the fleet's argument again: one directory holds both
+  // what a person wrote and what a command fetched, and only the second kind may
+  // be thrown away. Without this row `packs/` inherits `policiesDir`'s
+  // `user-typed` and survives a reset that is supposed to clear re-fetchable
+  // state.
+  { path: packsDir, class: "refetchable" },
 
   // ── Never touched ──
   // A downloaded daemon binary is large, version-pinned and re-verified on use,

package/src/hooks/fp-reset.ts

@@ -98,6 +98,7 @@ import {
   isDaemonSupportedPlatform,
   probeDaemonEndToEnd,
 } from "./daemon-service";
+import { readHooksConfig } from "./hooks-config";
 
 export interface ResetOutcome {
   /** Paths that existed and were removed. */
@@ -964,6 +965,33 @@ export function resetHome(from: number, to: number = LAYOUT_VERSION): ResetOutco
   // straight out of the same file. Both paths end at the same key, and only one
   // of them represents something a person typed.
   if (telemetryOptOut) updateConfig({ telemetry: { enabled: false } });
+  // `packs/` is resettable, but the package's default pack is also the offline
+  // enforcement floor. Restore it from the installed package before declaring
+  // the migration complete; third-party packs remain explicitly re-fetchable.
+  //
+  // Carrying `enabledPolicies` INTO the selection, not installing defaults over
+  // it. This is the upgrade path every existing user takes, and installing
+  // defaults meant a machine that had switched `block-force-push` and
+  // `block-kubectl` on came back with them off — guards that were denying
+  // before the upgrade and allowing after, with nothing said.
+  const carried = (() => {
+    try {
+      const names = readHooksConfig().enabledPolicies ?? [];
+      return names.length > 0 ? { only: names } : undefined;
+    } catch {
+      return undefined;
+    }
+  })();
+  // Deliberately does NOT install a pack. There is no copy in this package to
+  // install any more, and `resetHome` is synchronous and runs inside
+  // `failproofai update` — an upgrade that blocks on github.com, and fails when
+  // it is unreachable, is a worse upgrade than one that finishes.
+  //
+  // The carried names stay in config, which is what the no-pack fallback reads,
+  // so a machine mid-upgrade keeps enforcing exactly what it enforced before.
+  // `failproofai policies add core` turns them into a real pack when the user
+  // is online, and carries this selection into it.
+  void carried;
   // The step's OWN target, not LAYOUT_VERSION.
   //
   // Every step used to end stamping the current layout, which was harmless
@@ -1344,8 +1372,12 @@ function staleDaemonHint(): string[] {
         `[failproofai] daemon is ${skew.installed}, CLI is ${skew.expected}.`,
         `This machine is configured to REQUIRE the daemon. A daemon built against a`,
         `different on-disk layout refuses to start, and this version moved it — so the`,
-        `next reboot or restart can leave the service down, which denies every tool`,
-        `call until it is fixed.`,
+        // The wrap is load-bearing: "denies every tool call" is the consequence
+        // this message exists to state, and splitting it across two lines is
+        // what made the test asserting that phrase fail while the text looked
+        // perfectly correct to a human reading it.
+        `next reboot or restart can leave the service down, which`,
+        `denies every tool call until it is fixed.`,
         `Run \`failproofai update\` now to bring the daemon in line.`,
         ``,
       ];