Move built-in policies to installable policy packs

.gitignore

@@ -138,3 +138,6 @@ COMMIT_MSG.tmp
 
 # blog drafts (local, not for commit yet)
 /blog/
+
+# Generated by `bun run build:pack` — the builtins emitted as a policy pack.
+policy-pack/

__tests__/audit/engine-version-packs.test.ts

@@ -0,0 +1,111 @@
+// @vitest-environment node
+/**
+ * The audit cache key, and the one property that decides whether shipping pack
+ * support costs every existing user a cold rescan.
+ *
+ * `engineVersion` keys on-disk audit cache entries. A machine that has never
+ * installed a pack must hash EXACTLY as it did before packs existed — otherwise
+ * merely upgrading invalidates the cache and forces a full re-scan of every
+ * transcript (~104s, per the note on CACHE_TTL_MS) for a feature nobody is using.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createHash } from "node:crypto";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BUILTIN_POLICIES } from "@/src/hooks/builtin-policies";
+
+/** Exactly the pre-pack formula, reproduced here so the test is independent of
+ *  the implementation it checks. */
+function prePackEngineVersion(): string {
+  const blob = BUILTIN_POLICIES.map((p) => `${p.name}|${p.fn.toString()}`).sort().join("\n");
+  return createHash("sha1").update(blob).digest("hex").slice(0, 16);
+}
+
+const ARTIFACT = "export const hooks = [];\n";
+const DIGEST = createHash("sha256").update(ARTIFACT).digest("hex");
+
+let root: string;
+let prevEnv: string | undefined;
+
+/** Fresh module each time — engineVersion memoizes per process. */
+async function engineVersion(): Promise<string> {
+  const { getEngineVersionForTest } = await import("@/src/audit/cache");
+  return getEngineVersionForTest();
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "fpai-ev-packs-"));
+  mkdirSync(join(root, "artifacts"), { recursive: true });
+  writeFileSync(join(root, "artifacts", `${DIGEST}.mjs`), ARTIFACT);
+  prevEnv = process.env.FAILPROOFAI_PACK_DIR;
+  process.env.FAILPROOFAI_PACK_DIR = root;
+  vi.resetModules();
+});
+
+afterEach(() => {
+  if (prevEnv === undefined) delete process.env.FAILPROOFAI_PACK_DIR;
+  else process.env.FAILPROOFAI_PACK_DIR = prevEnv;
+  rmSync(root, { recursive: true, force: true });
+});
+
+import { vi } from "vitest";
+
+function installPack(id: string, version: string, artifact = ARTIFACT): void {
+  const digest = createHash("sha256").update(artifact).digest("hex");
+  writeFileSync(join(root, "artifacts", `${digest}.mjs`), artifact);
+  writeFileSync(
+    join(root, "installed.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      packs: [{
+        id, version,
+        source: `github:${id}@${version}`,
+        entry: `artifacts/${digest}.mjs`,
+        sha256: digest,
+        policies: [],
+      }],
+    }),
+  );
+}
+
+describe("engineVersion with packs", () => {
+  it("is UNCHANGED from the pre-pack formula when no pack is installed", async () => {
+    // The upgrade-cost guarantee. If this ever fails, shipping the change cold-
+    // rescans every existing user's whole transcript history.
+    expect(await engineVersion()).toBe(prePackEngineVersion());
+  });
+
+  it("changes once a pack is installed", async () => {
+    installPack("acme/finance", "1.2.0");
+    vi.resetModules();
+    expect(await engineVersion()).not.toBe(prePackEngineVersion());
+  });
+
+  it("changes again when the same pack moves to a new version", async () => {
+    installPack("acme/finance", "1.2.0");
+    vi.resetModules();
+    const at120 = await engineVersion();
+    installPack("acme/finance", "1.3.0");
+    vi.resetModules();
+    expect(await engineVersion()).not.toBe(at120);
+  });
+
+  it("changes when only the installed artifact digest changes", async () => {
+    installPack("acme/finance", "1.2.0");
+    vi.resetModules();
+    const original = await engineVersion();
+    installPack("acme/finance", "1.2.0", `${ARTIFACT}// patched\n`);
+    vi.resetModules();
+    expect(await engineVersion()).not.toBe(original);
+  });
+
+  it("falls back to the builtin-only hash when the manifest is unreadable", async () => {
+    // A corrupt manifest must not change the cache key: the packs did not load,
+    // so the audit that runs is a builtin-only audit and should hit the cache a
+    // builtin-only audit wrote.
+    writeFileSync(join(root, "installed.json"), "not json");
+    vi.resetModules();
+    expect(await engineVersion()).toBe(prePackEngineVersion());
+  });
+});

__tests__/e2e/cli/cli-args.e2e.test.ts

@@ -178,6 +178,14 @@ describe("policies: --help", () => {
   });
 });
 
+describe("pack: --help", () => {
+  it("prints help when the flag follows a nested subcommand", () => {
+    const result = runCli("pack", "add", "--help");
+    assertSuccess(result);
+    expect(result.stdout).toContain("install policy packs");
+  });
+});
+
 // ── policies --install ────────────────────────────────────────────────────────
 
 describe("policies --install: unknown flags", () => {

__tests__/e2e/hooks/builtin-policies-extended.e2e.test.ts

@@ -5,7 +5,7 @@
  * sanitize-connection-strings fixtures that trigger the PostToolUse hook.
  */
 import { describe, it } from "vitest";
-import { runHook, assertAllow, assertInstruct } from "../helpers/hook-runner";
+import { runHook, assertAllow, assertInstruct, assertPreToolUseDeny } from "../helpers/hook-runner";
 import { createFixtureEnv } from "../helpers/fixture-env";
 import { Payloads } from "../helpers/payloads";
 
@@ -36,19 +36,25 @@ describe("warn-package-publish extended", () => {
 
 // ── block-failproofai-commands — npx/bunx invocations ───────────────────────────
 
+// Both cases below asserted `allow` until `block-self-pause` was merged in and
+// its tokenizer replaced the anchored regex. The old test NAMES stated the hole
+// as the expectation — "regex requires failproofai at cmd start, not after npx"
+// — so a package runner in front of the binary walked through a default-on
+// self-protection policy. The merged matcher walks runner prefixes off before
+// it looks for the binary, so these deny now.
 describe("block-failproofai-commands extended", () => {
-  it("allows npx failproofai (regex requires failproofai at cmd start, not after npx)", () => {
+  it("blocks npx failproofai — a runner prefix no longer hides the binary", () => {
     const env = createFixtureEnv();
     env.writeConfig({ enabledPolicies: ["block-failproofai-commands"] });
     const result = runHook("PreToolUse", Payloads.preToolUse.bash("npx failproofai --list-policies", env.cwd), { homeDir: env.home });
-    assertAllow(result);
+    assertPreToolUseDeny(result);
   });
 
-  it("allows bunx failproofai (regex requires failproofai at cmd start, not after bunx)", () => {
+  it("blocks bunx failproofai — same, through the other runner", () => {
     const env = createFixtureEnv();
     env.writeConfig({ enabledPolicies: ["block-failproofai-commands"] });
     const result = runHook("PreToolUse", Payloads.preToolUse.bash("bunx failproofai --hook PreToolUse", env.cwd), { homeDir: env.home });
-    assertAllow(result);
+    assertPreToolUseDeny(result);
   });
 });
 

__tests__/e2e/hooks/builtin-policies.e2e.test.ts

@@ -486,19 +486,25 @@ describe("warn-package-publish extended", () => {
   });
 });
 
+// Both cases below asserted `allow` until `block-self-pause` was merged in and
+// its tokenizer replaced the anchored regex. The old test NAMES stated the hole
+// as the expectation — "regex requires failproofai at cmd start, not after npx"
+// — so a package runner in front of the binary walked through a default-on
+// self-protection policy. The merged matcher walks runner prefixes off before
+// it looks for the binary, so these deny now.
 describe("block-failproofai-commands extended", () => {
-  it("allows npx failproofai (regex requires failproofai at cmd start, not after npx)", () => {
+  it("blocks npx failproofai — a runner prefix no longer hides the binary", () => {
     const env = createFixtureEnv();
     env.writeConfig({ enabledPolicies: ["block-failproofai-commands"] });
     const result = runHook("PreToolUse", Payloads.preToolUse.bash("npx failproofai --list-policies", env.cwd), { homeDir: env.home });
-    assertAllow(result);
+    assertPreToolUseDeny(result);
   });
 
-  it("allows bunx failproofai (regex requires failproofai at cmd start, not after bunx)", () => {
+  it("blocks bunx failproofai — same, through the other runner", () => {
     const env = createFixtureEnv();
     env.writeConfig({ enabledPolicies: ["block-failproofai-commands"] });
     const result = runHook("PreToolUse", Payloads.preToolUse.bash("bunx failproofai --hook PreToolUse", env.cwd), { homeDir: env.home });
-    assertAllow(result);
+    assertPreToolUseDeny(result);
   });
 });
 

__tests__/e2e/hooks/pack-enforcement.e2e.test.ts

@@ -0,0 +1,193 @@
+// @vitest-environment node
+/**
+ * A pack, denying a real tool call through the real hook binary.
+ *
+ * Everything else about packs is tested at the unit level: the manifest parses,
+ * the loader tags, the digest verifies. None of that answers the only question
+ * that matters to a user — does an installed pack actually STOP the agent — and
+ * the layers between (config merge, registration order, per-CLI response shape)
+ * are exactly where a policy silently becomes decorative.
+ */
+import { describe, it, expect } from "vitest";
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { runHook, assertAllow, assertPreToolUseDeny } from "../helpers/hook-runner";
+import { createFixtureEnv } from "../helpers/fixture-env";
+import { Payloads } from "../helpers/payloads";
+
+const ENTRY = `
+  import { customPolicies, allow, deny } from "failproofai";
+  customPolicies.add({
+    name: "block-refunds",
+    description: "Block refunds above the approved limit",
+    match: { events: ["PreToolUse"] },
+    fn: async (ctx) => (String(ctx.toolInput?.command ?? "").includes("refund")
+      ? deny("refunds need a human")
+      : allow()),
+  });
+  customPolicies.add({
+    name: "block-payouts",
+    description: "Block payouts",
+    match: { events: ["PreToolUse"] },
+    fn: async (ctx) => (String(ctx.toolInput?.command ?? "").includes("payout")
+      ? deny("payouts need a human")
+      : allow()),
+  });
+`;
+const DIGEST = createHash("sha256").update(ENTRY).digest("hex");
+
+const policy = (name: string) => ({
+  name, description: `d-${name}`, category: "Finance", defaultEnabled: true,
+  match: { events: ["PreToolUse"] },
+});
+
+/** Install a pack into the fixture home, the way `pack add` would leave it. */
+function installPack(home: string, over: Record<string, unknown> = {}, entry = ENTRY): void {
+  const digest = createHash("sha256").update(entry).digest("hex");
+  const packs = join(home, ".failproofai", "policies", "packs");
+  mkdirSync(join(packs, "artifacts"), { recursive: true });
+  writeFileSync(join(packs, "artifacts", `${digest}.mjs`), entry, "utf8");
+  writeFileSync(
+    join(packs, "installed.json"),
+    JSON.stringify({
+      schemaVersion: 1,
+      packs: [{
+        id: "acme/finance", version: "1.2.0", source: "github:acme/finance@v1.2.0",
+        entry: `artifacts/${digest}.mjs`, sha256: digest,
+        policies: [policy("block-refunds"), policy("block-payouts")],
+        ...over,
+      }],
+    }),
+    "utf8",
+  );
+}
+
+const bash = (cmd: string, cwd: string) => Payloads.preToolUse.bash(cmd, cwd);
+
+describe("pack enforcement, end to end", () => {
+  it("denies a tool call a pack policy objects to", () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home);
+
+    const result = runHook("PreToolUse", bash("issue refund 500", env.cwd), { homeDir: env.home });
+    assertPreToolUseDeny(result);
+    expect(result.stdout + result.stderr).toContain("refunds need a human");
+  });
+
+  it("allows what the pack does not object to", () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home);
+    assertAllow(runHook("PreToolUse", bash("ls -la", env.cwd), { homeDir: env.home }));
+  });
+
+  it("enforces with NO builtin policies enabled — the pack is the only guard", () => {
+    // The layering claim made explicit: a pack adds enforcement rather than
+    // depending on any builtin being switched on.
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home);
+    assertPreToolUseDeny(runHook("PreToolUse", bash("send payout now", env.cwd), { homeDir: env.home }));
+  });
+
+  it("registers ONLY the selected policies", () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home, { enabled: ["block-refunds"] });
+
+    assertPreToolUseDeny(runHook("PreToolUse", bash("issue refund 500", env.cwd), { homeDir: env.home }));
+    // Taken out of the pack, so it must not fire even though the artifact
+    // registers it.
+    assertAllow(runHook("PreToolUse", bash("send payout now", env.cwd), { homeDir: env.home }));
+  });
+
+  it("DENIES when the artifact no longer matches its recorded digest", () => {
+    // This asserted a clean allow until the fail-closed contract landed, and the
+    // comment then said why: failing open was defensible only while compiled
+    // builtins enforced underneath. Once a pack can be the only thing standing
+    // between an agent and a machine, "the guard you were promised is not
+    // running" has to refuse rather than proceed quietly.
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home);
+    const packs = join(env.home, ".failproofai", "policies", "packs");
+    writeFileSync(join(packs, "artifacts", `${DIGEST}.mjs`), ENTRY + "\n// tampered\n", "utf8");
+
+    const result = runHook("PreToolUse", bash("issue refund 500", env.cwd), { homeDir: env.home });
+    assertPreToolUseDeny(result);
+    const out = result.stdout + result.stderr;
+    expect(out).toContain("acme/finance");
+    // The message must name the human command, because the agent cannot run it:
+    // block-failproofai-commands denies every failproofai invocation from a tool
+    // call, deliberately and unconditionally.
+    expect(out).toContain("failproofai pack list");
+  });
+
+  it("still denies only where the missing guards applied", () => {
+    // The deny is narrow, unlike the daemon's. An unreachable daemon means no
+    // evaluation happened at all, so nothing can be known safe; an unloadable
+    // pack has an ENUMERABLE set of missing guards, because every declared
+    // policy must carry a match.
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home);
+    const packs = join(env.home, ".failproofai", "policies", "packs");
+    writeFileSync(join(packs, "artifacts", `${DIGEST}.mjs`), ENTRY + "\n// tampered\n", "utf8");
+
+    // The pack's policies declare PreToolUse only, so a Stop event is untouched.
+    assertAllow(runHook("Stop", { hook_event_name: "Stop", cwd: env.cwd, session_id: "s" } as never, { homeDir: env.home }));
+  });
+
+  it("DENIES when a digest-valid artifact cannot be imported", () => {
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home, {}, "export const broken = ;\n");
+
+    const result = runHook("PreToolUse", bash("issue refund 500", env.cwd), { homeDir: env.home });
+    assertPreToolUseDeny(result);
+    expect(result.stdout + result.stderr).toContain("artifact failed to load");
+  });
+
+  it("does NOT deny for a tampered OBSERVE pack", () => {
+    // An observe pack evaluates and discards by construction, so denying on its
+    // behalf denies for something that would have allowed.
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home, { effect: "observe" });
+    const packs = join(env.home, ".failproofai", "policies", "packs");
+    writeFileSync(join(packs, "artifacts", `${DIGEST}.mjs`), ENTRY + "\n// tampered\n", "utf8");
+
+    assertAllow(runHook("PreToolUse", bash("issue refund 500", env.cwd), { homeDir: env.home }));
+  });
+
+  it("keeps enforcing builtins when the pack manifest is corrupt", () => {
+    // The layering property that makes fail-open defensible at all.
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: ["block-sudo"] });
+    const packs = join(env.home, ".failproofai", "policies", "packs");
+    mkdirSync(packs, { recursive: true });
+    writeFileSync(join(packs, "installed.json"), "not json", "utf8");
+
+    assertPreToolUseDeny(runHook("PreToolUse", bash("sudo rm -rf /", env.cwd), { homeDir: env.home }));
+  });
+
+  it("runs a pack policy in observe mode without denying, and WITHOUT crashing", () => {
+    // The allow is not enough on its own, and this test proved it: the first
+    // version of this passed against a real bug. The observe path read
+    // `cloudManaged!.id`, which is undefined for a pack, so every non-allow
+    // shadow verdict threw — the throw was swallowed by the evaluator, nothing
+    // was recorded, and the net result was an allow. Exactly what this asserted.
+    // A clean stderr is what separates "observed" from "crashed into an allow".
+    const env = createFixtureEnv();
+    env.writeConfig({ enabledPolicies: [] });
+    installPack(env.home, { effect: "observe" });
+
+    const result = runHook("PreToolUse", bash("issue refund 500", env.cwd), { homeDir: env.home });
+    assertAllow(result);
+    expect(result.stderr).not.toMatch(/threw:/);
+    expect(result.stderr).not.toMatch(/cloudManaged/);
+  });
+});