@erichll/pi-auto-review 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.12.0 - 2026-08-27
+
+- Add the private policy audit
+  compare current-project or anonymous global surface/command hotspots, denial
+  rates, approval sources, and rule-hit fingerprints; then review repeatedly
+  approved read-only operations as candidates for narrowly scoped `allow`
+  rules. Mutation, project execution, network, arbitrary-shell, unknown, and
+  custom-tool activity is called out as keep-`ask` evidence rather than an
+  automatic relaxation. The report does not edit policy or claim that an
+  unobserved rule is unused.
+- Add default-on, 180-day permission-policy auditing backed by built-in
+  `node:sqlite`. Permission decisions are immediately reduced to fixed command,
+  risk, path-class, source, and anonymous rule-hit aggregates; raw commands,
+  paths, URLs, credentials, request IDs, and project names are never stored.
+- Add `/auto-review-policy-audit` as an extension-owned custom-entry report.
+  It is not registered as an Agent tool or packaged skill, so audit reporting
+  adds no tool schema or skill metadata to the model context. Reports default
+  to the current project and can explicitly show an anonymous global aggregate.
+- Require Node.js 22.13.0 or newer. No SQLite CLI, system library, npm SQLite
+  package, RTK, or historical permission-log import is required.
+
+## 0.11.1 - 2026-08-25
+
+- Align the package version with `@erichll/pi-sandbox` `0.11.1`. No
+  pi-auto-review runtime or public API changes.
+
 ## 0.11.0 - 2026-08-24
 
 - **Structured network destination.** Network approval requests now carry

package/README.md

@@ -22,6 +22,7 @@ that dependency is a hard prerequisite (see [Install and enable](#install-and-en
 - [Reviewer context and token budgets](#reviewer-context-and-token-budgets)
 - [Sandbox integration](#sandbox-integration)
 - [Trust boundary](#trust-boundary)
+- [Permission policy audit](#permission-policy-audit)
 - [Telemetry](#telemetry)
 - [Real-model smoke test](#real-model-smoke-test)
 
@@ -32,6 +33,10 @@ that dependency is a hard prerequisite (see [Install and enable](#install-and-en
 > install the permission system separately (once per machine) before this
 > extension. Version 0.10.0 requires permission-system 27.x:
 
+Node.js 22.13.0 or newer is required. Permission auditing uses Node's built-in
+`node:sqlite`; it does not require a SQLite CLI, system SQLite library, or npm
+SQLite package.
+
 ```bash
 pi install npm:@gotgenes/pi-permission-system
 pi install npm:@erichll/pi-auto-review
@@ -100,6 +105,12 @@ Use the user-global file for normal customization. It may set any legal key:
 }
 ```
 
+For a complete `@gotgenes/pi-permission-system` config that wires
+`pi-auto-review` into the authorizer chain — a copyable baseline covering
+read/write/edit, a read-only bash allowlist, an MCP discovery policy, and a
+`path` deny block for secret and credential files — see
+[`examples/pi-permission-system.config.example.json`](examples/pi-permission-system.config.example.json).
+
 Package defaults:
 
 ```json
@@ -116,7 +127,11 @@ Package defaults:
   "breakGlassEnabled": true,
   "failureMode": "deny",
   "grantTtlMs": 60000,
-  "autoConfirmBoundedAllows": ["external_directory", "path"]
+  "autoConfirmBoundedAllows": ["external_directory", "path"],
+  "policyAudit": {
+    "enabled": true,
+    "retentionDays": 180
+  }
 }
 ```
 
@@ -130,6 +145,11 @@ and grant TTL, set `failureMode` to `"deny"`, set `breakGlassEnabled` to
 select a model, raise a trusted limit, or weaken fail-closed behavior. Invalid
 configuration disables the reviewer for that session.
 
+The trusted user config may set `policyAudit.enabled` and a retention of
+1–3,650 days. Project config may only set `enabled: false` or shorten the
+inherited retention; it cannot re-enable globally disabled collection or
+extend retention.
+
 ### Deadlines and retries
 
 `timeoutMs` is one deadline shared by model resolution, authentication, model
@@ -307,6 +327,44 @@ Writes to the installed reviewer package, its user-global configuration,
 project and global security configuration, and the global audit directory are
 deterministically denied.
 
+## Permission policy audit
+
+The extension observes terminal `permissions:decision` broadcasts and stores
+only daily, redacted aggregates. Collection is enabled by default and retains
+180 days. It starts when this version first initializes successfully; no
+permission-system JSONL or RTK history is read or imported.
+
+Before storage, Bash values become fixed signatures such as `git:push`,
+`rtk:git:status`, `npm:test`, or `<path-command>`. Paths become only
+`workspace`, `temp`, `home`, `external`, `sensitive`, or `unknown`. Request IDs,
+project locations, and matched-rule patterns are HMACed. The database never
+stores raw commands, paths, URLs, credentials, tool inputs, or project names.
+
+Data lives at
+`~/.pi/agent/extensions/pi-auto-review/policy-audit.sqlite`, beside an
+owner-only HMAC key. The directory is mode `0700`; the key, database, WAL, and
+SHM are mode `0600`. Initialization, lock, write, or corruption failures disable
+auditing and warn once without changing any permission result. A corrupt
+database is not deleted or rebuilt automatically. Disable new collection with:
+
+```json
+{
+  "policyAudit": { "enabled": false }
+}
+```
+
+Run `/auto-review-policy-audit` for a durable TUI report that is not sent to the
+LLM. Options are `--days 1..retention`, `--top 1..50`, `--min-count >=1`, and
+`--scope current|all`; defaults are `30`, `20`, `5`, and `current`.
+
+The report is an extension-owned custom entry. It is deliberately not exposed
+as an Agent tool or packaged skill, so neither a tool schema nor skill metadata
+is added to the model context. Permission changes remain a separate, explicit
+user operation.
+
+`PI_AUTO_REVIEW_AUDIT_FILE` remains a test/release observation sink. It is not
+an input to this audit and supplies no RTK token or parsing metrics.
+
 ## Telemetry
 
 Every actual model call emits an internal `review_attempt`; each approval emits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Fail-closed, model-backed approval broker for Pi: deterministically hard-denies dangerous operations, reviews dangerous boundaries with a reviewer model, and issues one-shot expiring grants that OS sandbox adapters must consume before retrying.",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.13.0"
   },
   "files": [
     "src",

package/src/config.json

@@ -11,5 +11,9 @@
   "breakGlassEnabled": true,
   "failureMode": "deny",
   "grantTtlMs": 60000,
-  "autoConfirmBoundedAllows": ["external_directory", "path"]
+  "autoConfirmBoundedAllows": ["external_directory", "path"],
+  "policyAudit": {
+    "enabled": true,
+    "retentionDays": 180
+  }
 }

package/src/index.ts

@@ -65,6 +65,13 @@ export {
   type SandboxRequestContext,
 } from "./integrations/sandbox.ts";
 import { parseHostPort } from "./integrations/sandbox.ts";
+import {
+  parsePolicyAuditArguments,
+  PolicyAuditController,
+  type PermissionDecisionLike,
+  type PolicyAuditArguments,
+  type PolicyAuditConfig,
+} from "./policy-audit/index.ts";
 export { parseHostPort };
 
 type ReasoningLevel =
@@ -92,6 +99,7 @@ export type Config = {
   failureMode: "deny" | "defer";
   grantTtlMs: number;
   autoConfirmBoundedAllows: readonly BoundedSurface[];
+  policyAudit: Readonly<PolicyAuditConfig>;
 };
 
 type CompletionMessage = {
@@ -296,6 +304,7 @@ const DEFAULT_CONFIG: Config = {
   failureMode: "deny",
   grantTtlMs: 60_000,
   autoConfirmBoundedAllows: Object.freeze(["external_directory", "path"]),
+  policyAudit: Object.freeze({ enabled: true, retentionDays: 180 }),
 };
 
 function writeOptionalAuditFile(event: unknown): void {
@@ -364,6 +373,7 @@ function validateConfig(value: unknown, source: string): Config {
     "failureMode",
     "grantTtlMs",
     "autoConfirmBoundedAllows",
+    "policyAudit",
   ]);
   const unknownKeys = Object.keys(raw).filter((key) => !allowedKeys.has(key));
   if (unknownKeys.length > 0) {
@@ -372,6 +382,10 @@ function validateConfig(value: unknown, source: string): Config {
     );
   }
   const config = { ...DEFAULT_CONFIG, ...raw };
+  config.policyAudit = {
+    ...DEFAULT_CONFIG.policyAudit,
+    ...(raw.policyAudit as Partial<PolicyAuditConfig> | undefined),
+  };
   if (
     typeof config.model !== "string" ||
     !config.model.trim() ||
@@ -453,11 +467,25 @@ function validateConfig(value: unknown, source: string): Config {
       `${EXTENSION_NAME}: maxReviewerInputTokens must be 2048..32768`,
     );
   }
+  if (raw.policyAudit !== undefined &&
+      (!raw.policyAudit || typeof raw.policyAudit !== "object" || Array.isArray(raw.policyAudit))) {
+    throw new Error(`${EXTENSION_NAME}: policyAudit must be an object`);
+  }
+  const policyAuditKeys = Object.keys((raw.policyAudit ?? {}) as Record<string, unknown>);
+  if (policyAuditKeys.some((key) => key !== "enabled" && key !== "retentionDays")) {
+    throw new Error(`${EXTENSION_NAME}: policyAudit only accepts enabled and retentionDays`);
+  }
+  if (typeof config.policyAudit.enabled !== "boolean" ||
+      !Number.isInteger(config.policyAudit.retentionDays) ||
+      config.policyAudit.retentionDays < 1 || config.policyAudit.retentionDays > 3_650) {
+    throw new Error(`${EXTENSION_NAME}: policyAudit requires enabled boolean and retentionDays 1..3650`);
+  }
   return {
     ...config,
     autoConfirmBoundedAllows: Object.freeze([
       ...config.autoConfirmBoundedAllows,
     ]),
+    policyAudit: Object.freeze({ ...config.policyAudit }),
   };
 }
 
@@ -500,11 +528,20 @@ export function applyUserConfig(
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`${EXTENSION_NAME}: ${source} must be an object`);
   }
+  const overlay = value as Record<string, unknown>;
+  if (overlay.policyAudit !== undefined &&
+      (!overlay.policyAudit || typeof overlay.policyAudit !== "object" || Array.isArray(overlay.policyAudit))) {
+    throw new Error(`${EXTENSION_NAME}: ${source} policyAudit must be an object`);
+  }
   return validateConfig(
     {
       ...packageConfig,
       autoConfirmBoundedAllows: [...packageConfig.autoConfirmBoundedAllows],
-      ...(value as Record<string, unknown>),
+      ...overlay,
+      policyAudit: {
+        ...packageConfig.policyAudit,
+        ...(overlay.policyAudit as object | undefined),
+      },
     },
     source,
   );
@@ -569,6 +606,7 @@ export function applyProjectConfig(
     "breakGlassEnabled",
     "failureMode",
     "autoConfirmBoundedAllows",
+    "policyAudit",
   ]);
   const forbidden = Object.keys(raw).filter((key) => !allowed.has(key));
   if (forbidden.length > 0) {
@@ -625,6 +663,27 @@ export function applyProjectConfig(
       ...new Set(raw.autoConfirmBoundedAllows as BoundedSurface[]),
     ];
   }
+  if (raw.policyAudit !== undefined) {
+    if (!raw.policyAudit || typeof raw.policyAudit !== "object" || Array.isArray(raw.policyAudit)) {
+      throw new Error(`${EXTENSION_NAME}: project policyAudit must be an object`);
+    }
+    const audit = raw.policyAudit as Record<string, unknown>;
+    const forbiddenAuditKeys = Object.keys(audit).filter((key) => key !== "enabled" && key !== "retentionDays");
+    if (forbiddenAuditKeys.length > 0) {
+      throw new Error(`${EXTENSION_NAME}: project policyAudit cannot set: ${forbiddenAuditKeys.join(", ")}`);
+    }
+    if (audit.enabled !== undefined && audit.enabled !== false) {
+      throw new Error(`${EXTENSION_NAME}: project policyAudit may only disable collection`);
+    }
+    if (audit.retentionDays !== undefined &&
+        (!Number.isInteger(audit.retentionDays) || Number(audit.retentionDays) < 1 || Number(audit.retentionDays) > trusted.policyAudit.retentionDays)) {
+      throw new Error(`${EXTENSION_NAME}: project policyAudit.retentionDays may only shorten retention`);
+    }
+    merged.policyAudit = {
+      enabled: audit.enabled === false ? false : trusted.policyAudit.enabled,
+      retentionDays: audit.retentionDays === undefined ? trusted.policyAudit.retentionDays : Number(audit.retentionDays),
+    };
+  }
   return Object.freeze(validateConfig(merged, "effective project config"));
 }
 
@@ -1901,6 +1960,33 @@ export type PiAutoReviewExtensionOptions = {
   allowUntrustedWorkspace?: boolean;
 };
 
+const POLICY_AUDIT_ENTRY_TYPE = "pi-auto-review-policy-audit";
+
+function renderPolicyAuditEntry(
+  entry: { data?: unknown },
+  _options: unknown,
+  theme: { fg(color: string, text: string): string },
+): { render(width: number): string[]; invalidate(): void } | undefined {
+  const markdown = entry.data && typeof entry.data === "object" &&
+      typeof (entry.data as { markdown?: unknown }).markdown === "string"
+    ? (entry.data as { markdown: string }).markdown
+    : undefined;
+  if (!markdown) return undefined;
+  return {
+    render(width: number) {
+      const max = Math.max(20, width - 2);
+      return markdown.split("\n").flatMap((line) => {
+        const output: string[] = [];
+        for (let offset = 0; offset < Math.max(1, line.length); offset += max) {
+          output.push(theme.fg("muted", line.slice(offset, offset + max)));
+        }
+        return output;
+      });
+    },
+    invalidate() {},
+  };
+}
+
 export function createPiAutoReviewExtension(
   options: PiAutoReviewExtensionOptions = {},
 ): (pi: ExtensionAPI) => void {
@@ -1916,6 +2002,7 @@ export function createPiAutoReviewExtension(
   return (pi: ExtensionAPI): void => {
   try {
     pi.registerEntryRenderer(USER_REVIEW_ENTRY_TYPE, renderUserReviewEntry);
+    pi.registerEntryRenderer(POLICY_AUDIT_ENTRY_TYPE, renderPolicyAuditEntry);
   } catch {
     // Renderer registration is observational.
   }
@@ -1936,6 +2023,36 @@ export function createPiAutoReviewExtension(
     () => config.autoConfirmBoundedAllows,
   );
   const reviewWidget = new UserReviewWidgetController();
+  const policyAudit = new PolicyAuditController({
+    config: () => config.policyAudit,
+    cwd: () => context?.cwd,
+    warn: (message) => {
+      console.error(message);
+      notifyUserReview(context, { type: "warning", message });
+    },
+  });
+
+  const runPolicyAuditReport = async (args: PolicyAuditArguments) =>
+    policyAudit.report(args);
+
+  pi.registerCommand("auto-review-policy-audit", {
+    description: "Show a persistent, redacted permission-policy audit report",
+    handler: async (rawArgs, ctx) => {
+      try {
+        const args = parsePolicyAuditArguments(rawArgs, config.policyAudit.retentionDays);
+        const result = await runPolicyAuditReport(args);
+        pi.appendEntry(POLICY_AUDIT_ENTRY_TYPE, {
+          markdown: result.markdown,
+          report: result.report,
+        });
+      } catch (error) {
+        ctx.ui.notify(
+          `Permission policy audit unavailable: ${error instanceof Error ? error.message : String(error)}`,
+          "warning",
+        );
+      }
+    },
+  });
 
   const emitTelemetry = (event: ReviewerTelemetryEvent): void => {
     writeOptionalAuditFile(event);
@@ -2288,6 +2405,7 @@ export function createPiAutoReviewExtension(
       );
       context = ctx;
       broker = createBroker();
+      policyAudit.warmup();
       try {
         disposeBrokerService = publishBoundaryBroker(broker);
       } catch (error) {
@@ -2320,6 +2438,7 @@ export function createPiAutoReviewExtension(
 
   pi.events.on("permissions:decision", (event) => {
     reviewWidget.permissionDecision(event);
+    policyAudit.record(event as PermissionDecisionLike);
   });
 
   pi.events.on("permissions:ready", (event) => {
@@ -2516,7 +2635,7 @@ export function createPiAutoReviewExtension(
     }
   });
 
-  pi.on("session_shutdown", () => {
+  pi.on("session_shutdown", async () => {
     shuttingDown = true;
     registrationEpoch++;
     reviewWidget.clear(context);
@@ -2530,6 +2649,7 @@ export function createPiAutoReviewExtension(
     reviewResults.clear();
     uiAutoConfirmer.clear();
     context = undefined;
+    await policyAudit.close();
   });
   };
 }

package/src/policy-audit/classifier.ts

@@ -0,0 +1,234 @@
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, relative, resolve } from "node:path";
+
+export type PolicyAuditRisk =
+  | "read_only"
+  | "workspace_mutation"
+  | "project_code_execution"
+  | "network"
+  | "network_mutation"
+  | "arbitrary_shell"
+  | "unknown";
+
+export type PolicyAuditPathClass =
+  | "workspace"
+  | "temp"
+  | "home"
+  | "external"
+  | "sensitive"
+  | "unknown";
+
+export type PolicyAuditCommandFeature =
+  | "env_prefix"
+  | "compound"
+  | "pipeline"
+  | "relative_executable";
+
+export type ClassifiedPermission = {
+  surface: string;
+  signature: string;
+  bashCategory: string;
+  risk: PolicyAuditRisk;
+  pathClass: PolicyAuditPathClass;
+  features: readonly PolicyAuditCommandFeature[];
+};
+
+const KNOWN_SURFACES = new Set([
+  "bash",
+  "bash_escalated",
+  "read",
+  "write",
+  "edit",
+  "grep",
+  "find",
+  "ls",
+  "path",
+  "external_directory",
+  "skill",
+  "mcp",
+  "network",
+]);
+
+const SENSITIVE_PATH = /(?:^|[/\\])(?:\.ssh|\.aws|\.gnupg|\.kube|\.azure|\.npmrc|\.netrc|\.env(?:\.[^/\\]+)?|auth\.json|credentials?)(?:[/\\]|$)/i;
+const READ_ONLY_COMMANDS = new Set([
+  "cat", "find", "grep", "head", "ls", "pwd", "rg", "sed", "sort",
+  "stat", "tail", "wc", "which",
+]);
+const MUTATING_COMMANDS = new Set([
+  "chmod", "chown", "cp", "install", "ln", "mkdir", "mv", "rm", "rmdir",
+  "touch", "truncate",
+]);
+const NETWORK_COMMANDS = new Set(["curl", "dig", "host", "nc", "ping", "ssh", "wget"]);
+const SHELL_COMMANDS = new Set(["bash", "dash", "fish", "sh", "zsh"]);
+const GIT_ACTIONS = new Set([
+  "add", "branch", "checkout", "clean", "clone", "commit", "diff", "fetch",
+  "log", "merge", "pull", "push", "rebase", "remote", "reset", "restore",
+  "send-pack", "show", "status", "switch", "tag",
+]);
+const RTK_ACTIONS = new Set(["diff", "find", "grep", "ls", "read", "rg", "smart", "wc"]);
+const PACKAGE_ACTIONS = new Set([
+  "add", "build", "check", "coverage", "dev", "format", "install", "lint",
+  "publish", "start", "test", "typecheck", "uninstall", "update", "upgrade",
+]);
+
+function within(path: string, parent: string): boolean {
+  const rel = relative(parent, path);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+export function classifyPath(
+  value: unknown,
+  cwd: string,
+  home = homedir(),
+  temp = tmpdir(),
+): PolicyAuditPathClass {
+  if (typeof value !== "string" || !value.trim()) return "unknown";
+  const raw = value.trim();
+  if (SENSITIVE_PATH.test(raw)) return "sensitive";
+  if (!raw.startsWith("/") && !raw.startsWith("~") && !raw.startsWith(".")) {
+    return "unknown";
+  }
+  const expanded = raw === "~" || raw.startsWith("~/")
+    ? resolve(home, raw.slice(2))
+    : resolve(cwd, raw);
+  if (within(expanded, resolve(cwd))) return "workspace";
+  if (within(expanded, resolve(temp))) return "temp";
+  if (within(expanded, resolve(home))) return "home";
+  return "external";
+}
+
+function shellTokens(command: string): string[] {
+  return command
+    .trim()
+    .split(/\s+/u)
+    .map((token) => token.replace(/^["']|["']$/g, ""));
+}
+
+function executableIndex(tokens: readonly string[]): number {
+  let index = 0;
+  if (tokens[index] === "env") index++;
+  while (index < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=.*/.test(tokens[index])) {
+    index++;
+  }
+  return index;
+}
+
+function safeCommandName(token: string | undefined): string {
+  if (!token) return "unknown";
+  const name = token.split(/[\\/]/).at(-1)?.toLowerCase() || "unknown";
+  return /^[a-z0-9][a-z0-9+._-]{0,31}$/.test(name) ? name : "unknown";
+}
+
+function knownSignature(tokens: readonly string[], index: number): string {
+  const executable = safeCommandName(tokens[index]);
+  const sub = safeCommandName(tokens[index + 1]);
+  const third = safeCommandName(tokens[index + 2]);
+  if (executable === "rtk") {
+    if (sub === "git") return `rtk:git:${GIT_ACTIONS.has(third) ? third : "other"}`;
+    return `rtk:${RTK_ACTIONS.has(sub) ? sub : "other"}`;
+  }
+  if (executable === "git") return `git:${GIT_ACTIONS.has(sub) ? sub : "other"}`;
+  if (["npm", "pnpm", "yarn", "bun"].includes(executable)) {
+    const action = sub === "run" ? third : sub;
+    return `${executable}:${PACKAGE_ACTIONS.has(action) ? action : "custom-script"}`;
+  }
+  if (READ_ONLY_COMMANDS.has(executable) || MUTATING_COMMANDS.has(executable) ||
+      NETWORK_COMMANDS.has(executable) || SHELL_COMMANDS.has(executable)) {
+    return executable;
+  }
+  if (tokens[index]?.includes("/") || tokens[index]?.startsWith(".")) {
+    return "<path-command>";
+  }
+  return "<other-command>";
+}
+
+function commandRisk(signature: string, executable: string, command: string): PolicyAuditRisk {
+  if (/&&|\|\||;|\n|`|\$\(|(^|[^|])\|([^|]|$)/.test(command)) return "arbitrary_shell";
+  if (["git:push", "git:send-pack", "rtk:git:push", "rtk:git:send-pack"].includes(signature)) return "network_mutation";
+  if (/^(?:npm|pnpm|yarn|bun):(install|publish|add|upgrade|update)$/.test(signature)) {
+    return signature.endsWith(":publish") ? "network_mutation" : "project_code_execution";
+  }
+  if (/^(?:npm|pnpm|yarn|bun):/.test(signature)) return "project_code_execution";
+  if (NETWORK_COMMANDS.has(executable)) {
+    return /(?:^|\s)(?:--upload-file|-T|-X\s*(?:POST|PUT|PATCH|DELETE)|--data|-d)(?:\s|=|$)/i.test(command)
+      ? "network_mutation"
+      : "network";
+  }
+  if (MUTATING_COMMANDS.has(executable) || ["git:add", "git:commit", "git:reset", "git:clean", "git:checkout", "git:restore", "git:rebase", "rtk:git:add", "rtk:git:commit"].includes(signature)) {
+    return "workspace_mutation";
+  }
+  if (READ_ONLY_COMMANDS.has(executable) || /^(?:rtk:)?git:(?:status|diff|log|show|branch)$/.test(signature)) {
+    return "read_only";
+  }
+  if (SHELL_COMMANDS.has(executable) || signature === "<path-command>") {
+    return "arbitrary_shell";
+  }
+  return "unknown";
+}
+
+export function classifyBash(command: unknown, cwd: string): ClassifiedPermission {
+  if (typeof command !== "string" || !command.trim()) {
+    return { surface: "bash", signature: "<other-command>", bashCategory: "unknown", risk: "unknown", pathClass: "unknown", features: [] };
+  }
+  const tokens = shellTokens(command);
+  const index = executableIndex(tokens);
+  const executable = safeCommandName(tokens[index]);
+  const signature = knownSignature(tokens, index);
+  const features: PolicyAuditCommandFeature[] = [];
+  if (index > 0) features.push("env_prefix");
+  if (/&&|\|\||;|\n|`|\$\(/.test(command)) features.push("compound");
+  if (/(^|[^|])\|([^|]|$)/.test(command)) features.push("pipeline");
+  if (tokens[index]?.includes("/") || tokens[index]?.startsWith(".")) features.push("relative_executable");
+  const bashCategory = /^(?:rtk:)?git:/.test(signature)
+    ? "version_control"
+    : /^(?:npm|pnpm|yarn|bun):/.test(signature)
+      ? "package_script"
+      : NETWORK_COMMANDS.has(executable)
+        ? "network"
+        : READ_ONLY_COMMANDS.has(executable) || MUTATING_COMMANDS.has(executable)
+          ? "filesystem"
+          : "shell";
+  const pathToken = tokens.slice(index + 1)
+    .map((token) => token.includes("=") ? token.slice(token.indexOf("=") + 1) : token.replace(/^@/, ""))
+    .find((token) => token.startsWith("/") || token.startsWith("./") || token.startsWith("../") || token.startsWith("~/"));
+  return {
+    surface: "bash",
+    signature,
+    bashCategory,
+    risk: commandRisk(signature, executable, command),
+    pathClass: classifyPath(pathToken, cwd),
+    features: [...new Set(features)].sort(),
+  };
+}
+
+export function classifyPermission(surfaceValue: unknown, value: unknown, cwd: string): ClassifiedPermission {
+  const rawSurface = typeof surfaceValue === "string" ? surfaceValue.trim().toLowerCase() : "";
+  if (rawSurface === "bash" || rawSurface === "bash_escalated") {
+    const classified = classifyBash(value, cwd);
+    return { ...classified, surface: rawSurface || "bash" };
+  }
+  const surface = KNOWN_SURFACES.has(rawSurface) ? rawSurface : "custom_tool";
+  if (["path", "external_directory", "read", "write", "edit"].includes(surface)) {
+    const pathClass = classifyPath(value, cwd);
+    const risk = surface === "read"
+      ? "read_only"
+      : surface === "write" || surface === "edit"
+        ? "workspace_mutation"
+        : "unknown";
+    return { surface, signature: `<${surface}>`, bashCategory: "not_bash", risk, pathClass, features: [] };
+  }
+  if (["grep", "find", "ls"].includes(surface)) {
+    return { surface, signature: `<${surface}>`, bashCategory: "not_bash", risk: "read_only", pathClass: "unknown", features: [] };
+  }
+  if (surface === "network") {
+    return { surface, signature: "<network>", bashCategory: "not_bash", risk: "network", pathClass: "unknown", features: [] };
+  }
+  return {
+    surface,
+    signature: surface === "custom_tool" ? "<custom-tool>" : `<${surface}>`,
+    bashCategory: "not_bash",
+    risk: "unknown",
+    pathClass: "unknown",
+    features: [],
+  };
+}

package/src/policy-audit/index.ts

@@ -0,0 +1,172 @@
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+import { classifyPermission } from "./classifier.ts";
+import { buildPolicyAuditReport, renderPolicyAuditMarkdown, type PolicyAuditReport } from "./report.ts";
+import { defaultPolicyAuditDirectory, PolicyAuditStore, type PolicyAuditStoreOptions } from "./store.ts";
+
+export * from "./classifier.ts";
+export * from "./report.ts";
+export * from "./store.ts";
+
+export type PolicyAuditConfig = { enabled: boolean; retentionDays: number };
+
+export type PermissionDecisionLike = {
+  requestId?: unknown;
+  surface?: unknown;
+  value?: unknown;
+  result?: unknown;
+  resolution?: unknown;
+  origin?: unknown;
+  matchedPattern?: unknown;
+  forwarding?: unknown;
+};
+
+export type PolicyAuditArguments = { days: number; top: number; minCount: number; scope: "current" | "all" };
+
+const PERMISSION_RESOLUTIONS = new Set([
+  "policy_allow",
+  "policy_deny",
+  "session_approved",
+  "infrastructure_auto_allowed",
+  "user_approved",
+  "user_approved_for_session",
+  "user_denied",
+  "auto_approved",
+  "confirmation_unavailable",
+  "gate_error",
+]);
+
+export function parsePolicyAuditArguments(raw: string, retentionDays: number): PolicyAuditArguments {
+  const result: PolicyAuditArguments = { days: Math.min(30, retentionDays), top: 20, minCount: 5, scope: "current" };
+  const tokens = raw.trim() ? raw.trim().split(/\s+/u) : [];
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index];
+    const [flag, inline] = token.split("=", 2);
+    const value = inline ?? tokens[++index];
+    if (!value) throw new Error(`missing value for ${flag}`);
+    if (flag === "--scope") {
+      if (value !== "current" && value !== "all") throw new Error("--scope must be current or all");
+      result.scope = value;
+      continue;
+    }
+    const numeric = Number(value);
+    if (!Number.isInteger(numeric)) throw new Error(`${flag} must be an integer`);
+    if (flag === "--days" && numeric >= 1 && numeric <= retentionDays) result.days = numeric;
+    else if (flag === "--top" && numeric >= 1 && numeric <= 50) result.top = numeric;
+    else if (flag === "--min-count" && numeric >= 1) result.minCount = numeric;
+    else if (!["--days", "--top", "--min-count"].includes(flag)) throw new Error(`unknown option ${flag}`);
+    else throw new Error(`${flag} is outside its allowed range`);
+  }
+  return result;
+}
+
+export type PolicyAuditControllerOptions = {
+  config: () => Readonly<PolicyAuditConfig>;
+  cwd: () => string | undefined;
+  directory?: string;
+  warn: (message: string) => void;
+  storeOptions?: Omit<PolicyAuditStoreOptions, "directory" | "retentionDays">;
+};
+
+export class PolicyAuditController {
+  private storePromise?: Promise<PolicyAuditStore>;
+  private disabled = false;
+  private warned = false;
+  private queue = Promise.resolve();
+
+  constructor(private readonly options: PolicyAuditControllerOptions) {}
+
+  warmup(): void {
+    if (this.options.config().enabled) void this.getStore().catch(() => undefined);
+  }
+
+  private failure(error: unknown): never {
+    this.disabled = true;
+    const message = `pi-auto-review: policy audit disabled: ${error instanceof Error ? error.message : String(error)}`;
+    if (!this.warned) {
+      this.warned = true;
+      this.options.warn(message);
+    }
+    throw error;
+  }
+
+  private async getStore(): Promise<PolicyAuditStore> {
+    if (this.disabled) throw new Error("policy audit is unavailable");
+    if (!this.storePromise) {
+      const config = this.options.config();
+      this.storePromise = PolicyAuditStore.open({
+        directory: this.options.directory ?? defaultPolicyAuditDirectory(homedir()),
+        retentionDays: config.retentionDays,
+        ...this.options.storeOptions,
+      }).catch((error) => this.failure(error));
+    }
+    return this.storePromise;
+  }
+
+  record(event: PermissionDecisionLike): void {
+    const config = this.options.config();
+    const cwd = this.options.cwd();
+    if (!config.enabled || this.disabled || !cwd) return;
+    if (typeof event.requestId !== "string" ||
+        (event.result !== "allow" && event.result !== "deny") ||
+        typeof event.resolution !== "string") return;
+    const result: "allow" | "deny" = event.result;
+    // The raw value is classified synchronously and is never captured by the
+    // asynchronous queue or handed to SQLite.
+    const classified = classifyPermission(event.surface, event.value, cwd);
+    const digest = (kind: string, value: string) =>
+      createHash("sha256").update(`${kind}\0${value}`).digest("hex");
+    const rawOrigin = typeof event.origin === "string" ? event.origin.toLowerCase() : "";
+    const origin = rawOrigin.includes("project")
+      ? "project"
+      : rawOrigin.includes("user") || rawOrigin.includes("global")
+        ? "user"
+        : rawOrigin.includes("default") || rawOrigin.includes("package")
+          ? "default"
+          : rawOrigin ? "other" : "none";
+    const sanitized = {
+      ...classified,
+      requestId: digest("request", event.requestId),
+      result,
+      resolution: PERMISSION_RESOLUTIONS.has(event.resolution) ? event.resolution : "unknown",
+      origin,
+      forwarded: event.forwarding !== null && event.forwarding !== undefined,
+      matchedPattern: typeof event.matchedPattern === "string"
+        ? digest("rule", event.matchedPattern)
+        : undefined,
+    };
+    this.queue = this.queue
+      .then(async () => (await this.getStore()).record(cwd, sanitized))
+      .then(() => undefined)
+      .catch((error) => {
+        try { this.failure(error); } catch { /* observational failure is contained */ }
+      });
+  }
+
+  async report(args: PolicyAuditArguments): Promise<{ report: PolicyAuditReport; markdown: string }> {
+    const config = this.options.config();
+    if (!config.enabled && !this.storePromise) throw new Error("policy audit collection is disabled by configuration");
+    if (args.days > config.retentionDays) throw new Error(`days must be 1..${config.retentionDays}`);
+    await this.queue;
+    const cwd = this.options.cwd();
+    if (!cwd) throw new Error("policy audit has no active project context");
+    const store = await this.getStore();
+    let result;
+    try {
+      result = store.query({ ...args, projectPath: cwd });
+    } catch (error) {
+      return this.failure(error);
+    }
+    const report = buildPolicyAuditReport(result, args);
+    return { report, markdown: renderPolicyAuditMarkdown(report) };
+  }
+
+  async close(): Promise<void> {
+    await this.queue;
+    // Detach before awaiting so concurrent shutdowns cannot double-close.
+    const storePromise = this.storePromise;
+    this.storePromise = undefined;
+    const store = await storePromise?.catch(() => undefined);
+    store?.close();
+  }
+}

package/src/policy-audit/report.ts

@@ -0,0 +1,140 @@
+import type { PolicyAuditAggregateRow, PolicyAuditQueryResult } from "./store.ts";
+
+export const POLICY_AUDIT_REPORT_VERSION = 1 as const;
+
+export type PolicyAuditReportItem = { name: string; count: number; denied: number; denialRate: number };
+
+export type PolicyAuditReport = {
+  version: typeof POLICY_AUDIT_REPORT_VERSION;
+  scope: "current" | "all";
+  days: number;
+  collectingSince: string;
+  fromDay: string;
+  throughDay: string;
+  total: number;
+  allowed: number;
+  denied: number;
+  denialRate: number;
+  surfaces: PolicyAuditReportItem[];
+  tools: PolicyAuditReportItem[];
+  bashCategories: PolicyAuditReportItem[];
+  approvalSources: PolicyAuditReportItem[];
+  lowRiskReviewCandidates: PolicyAuditReportItem[];
+  keepAskRecommendations: PolicyAuditReportItem[];
+  ruleFingerprints: Array<{ fingerprint: string; count: number }>;
+  warnings: string[];
+};
+
+export type PolicyAuditReportOptions = {
+  scope: "current" | "all";
+  days: number;
+  top: number;
+  minCount: number;
+};
+
+function rate(denied: number, total: number): number {
+  return total === 0 ? 0 : Math.round((denied / total) * 10_000) / 100;
+}
+
+function rank(
+  rows: readonly PolicyAuditAggregateRow[],
+  key: (row: PolicyAuditAggregateRow) => string,
+  top: number,
+  minCount: number,
+): PolicyAuditReportItem[] {
+  const grouped = new Map<string, { count: number; denied: number }>();
+  for (const row of rows) {
+    const name = key(row);
+    const current = grouped.get(name) ?? { count: 0, denied: 0 };
+    current.count += row.count;
+    if (row.result === "deny") current.denied += row.count;
+    grouped.set(name, current);
+  }
+  return [...grouped]
+    .map(([name, value]) => ({ name, ...value, denialRate: rate(value.denied, value.count) }))
+    .filter((item) => item.count >= minCount)
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name))
+    .slice(0, top);
+}
+
+function reviewed(row: PolicyAuditAggregateRow): boolean {
+  return ["user_approved", "user_approved_for_session", "user_denied", "auto_approved"].includes(row.resolution);
+}
+
+export function buildPolicyAuditReport(
+  result: PolicyAuditQueryResult,
+  options: PolicyAuditReportOptions,
+): PolicyAuditReport {
+  const total = result.rows.reduce((sum, row) => sum + row.count, 0);
+  const denied = result.rows.filter((row) => row.result === "deny").reduce((sum, row) => sum + row.count, 0);
+  const lowRisk = result.rows.filter((row) => row.risk === "read_only" && reviewed(row));
+  const keepAsk = result.rows.filter((row) =>
+    ["workspace_mutation", "project_code_execution", "network", "network_mutation", "arbitrary_shell", "unknown"].includes(row.risk)
+  );
+  const fingerprintCounts = new Map<string, number>();
+  for (const row of result.rows) {
+    if (row.ruleFingerprint === "none") continue;
+    fingerprintCounts.set(row.ruleFingerprint, (fingerprintCounts.get(row.ruleFingerprint) ?? 0) + row.count);
+  }
+  const warnings = [
+    "Counts begin at first successful enablement; no historical logs are imported.",
+    "Rule fingerprints are anonymous hit indicators, not proof that unlisted rules are unused.",
+    "High frequency alone must not be used to relax mutation, network, arbitrary-shell, unknown, or custom-tool policy.",
+  ];
+  if (total === 0) warnings.unshift("No matching permission decisions were collected for this window and scope.");
+  return {
+    version: POLICY_AUDIT_REPORT_VERSION,
+    scope: options.scope,
+    days: options.days,
+    collectingSince: result.collectingSince,
+    fromDay: result.fromDay,
+    throughDay: result.throughDay,
+    total,
+    allowed: total - denied,
+    denied,
+    denialRate: rate(denied, total),
+    surfaces: rank(result.rows, (row) => row.surface, options.top, options.minCount),
+    tools: rank(result.rows, (row) => row.signature, options.top, options.minCount),
+    bashCategories: rank(result.rows.filter((row) => row.bashCategory !== "not_bash"), (row) => row.bashCategory, options.top, options.minCount),
+    approvalSources: rank(result.rows, (row) => `${row.resolution}/${row.origin}${row.forwarded ? "/forwarded" : ""}`, options.top, options.minCount),
+    lowRiskReviewCandidates: rank(lowRisk, (row) => `${row.surface}:${row.signature}`, options.top, options.minCount),
+    keepAskRecommendations: rank(keepAsk, (row) => `${row.risk}:${row.surface}:${row.signature}`, options.top, options.minCount),
+    ruleFingerprints: [...fingerprintCounts]
+      .map(([fingerprint, count]) => ({ fingerprint, count }))
+      .filter((item) => item.count >= options.minCount)
+      .sort((a, b) => b.count - a.count || a.fingerprint.localeCompare(b.fingerprint))
+      .slice(0, options.top),
+    warnings,
+  };
+}
+
+function itemLines(items: readonly PolicyAuditReportItem[]): string[] {
+  return items.length === 0
+    ? ["- None above the minimum count."]
+    : items.map((item) => `- ${item.name}: ${item.count} (${item.denied} denied, ${item.denialRate}% denial)`);
+}
+
+export function renderPolicyAuditMarkdown(report: PolicyAuditReport): string {
+  const fingerprints = report.ruleFingerprints.length === 0
+    ? ["- None above the minimum count."]
+    : report.ruleFingerprints.map((item) => `- ${item.fingerprint}: ${item.count}`);
+  return [
+    "# Permission policy audit",
+    "",
+    `Scope: **${report.scope}** · Window: **${report.fromDay}–${report.throughDay}** · Collecting since: **${report.collectingSince}**`,
+    `Decisions: **${report.total}** · Allowed: **${report.allowed}** · Denied: **${report.denied}** · Denial rate: **${report.denialRate}%**`,
+    "",
+    "## Surface hotspots", "", ...itemLines(report.surfaces), "",
+    "## Tool and command signatures", "", ...itemLines(report.tools), "",
+    "## Bash semantic categories", "", ...itemLines(report.bashCategories), "",
+    "## Approval sources", "", ...itemLines(report.approvalSources), "",
+    "## Low-risk review candidates", "",
+    "These read-only requests were still reviewed; inspect them before considering a narrower allow rule.",
+    ...itemLines(report.lowRiskReviewCandidates), "",
+    "## Keep-ask recommendations", "",
+    "These mutation, execution, network, shell, or unknown requests should remain ask-by-default.",
+    ...itemLines(report.keepAskRecommendations), "",
+    "## Anonymous rule-hit fingerprints", "", ...fingerprints, "",
+    "## Warnings", "", ...report.warnings.map((warning) => `- ${warning}`),
+  ].join("\n");
+}

package/src/policy-audit/store.ts

@@ -0,0 +1,298 @@
+import { createHmac, randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ClassifiedPermission } from "./classifier.ts";
+
+export const POLICY_AUDIT_SCHEMA_VERSION = 1;
+export const POLICY_AUDIT_DATABASE_NAME = "policy-audit.sqlite";
+export const POLICY_AUDIT_KEY_NAME = "policy-audit.key";
+
+type RunResult = { changes: number | bigint };
+type Statement = {
+  run(...params: unknown[]): RunResult;
+  get(...params: unknown[]): Record<string, unknown> | undefined;
+  all(...params: unknown[]): Record<string, unknown>[];
+};
+type Database = {
+  exec(sql: string): void;
+  prepare(sql: string): Statement;
+  close(): void;
+};
+type SqliteModule = { DatabaseSync: new (path: string, options?: Record<string, unknown>) => Database };
+
+export type SanitizedPermissionDecision = ClassifiedPermission & {
+  requestId: string;
+  result: "allow" | "deny";
+  resolution: string;
+  origin: string;
+  forwarded: boolean;
+  matchedPattern?: string;
+};
+
+export type PolicyAuditStoreOptions = {
+  directory: string;
+  retentionDays: number;
+  now?: () => Date;
+  sqliteLoader?: () => Promise<SqliteModule>;
+};
+
+export type PolicyAuditQuery = {
+  days: number;
+  top: number;
+  minCount: number;
+  scope: "current" | "all";
+  projectPath: string;
+};
+
+export type PolicyAuditAggregateRow = {
+  surface: string;
+  signature: string;
+  bashCategory: string;
+  risk: string;
+  pathClass: string;
+  result: string;
+  resolution: string;
+  origin: string;
+  forwarded: boolean;
+  features: string;
+  ruleFingerprint: string;
+  count: number;
+};
+
+export type PolicyAuditQueryResult = {
+  collectingSince: string;
+  fromDay: string;
+  throughDay: string;
+  rows: PolicyAuditAggregateRow[];
+};
+
+function dayString(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+function addDays(date: Date, delta: number): Date {
+  const copy = new Date(date);
+  copy.setUTCDate(copy.getUTCDate() + delta);
+  return copy;
+}
+
+function loadOrCreateKey(directory: string): Buffer {
+  const keyPath = join(directory, POLICY_AUDIT_KEY_NAME);
+  try {
+    const fd = openSync(keyPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+      writeFileSync(fd, randomBytes(32));
+    } finally {
+      closeSync(fd);
+    }
+  } catch (error) {
+    if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+      throw error;
+    }
+  }
+  chmodSync(keyPath, 0o600);
+  const key = readFileSync(keyPath);
+  if (key.length !== 32) throw new Error("policy audit key has an invalid length");
+  return key;
+}
+
+function normalizeOrigin(value: string): string {
+  const lowered = value.toLowerCase();
+  if (lowered.includes("project")) return "project";
+  if (lowered.includes("user") || lowered.includes("global")) return "user";
+  if (lowered.includes("default") || lowered.includes("package")) return "default";
+  return value === "none" ? "none" : "other";
+}
+
+export class PolicyAuditStore {
+  static async open(options: PolicyAuditStoreOptions): Promise<PolicyAuditStore> {
+    mkdirSync(options.directory, { recursive: true, mode: 0o700 });
+    chmodSync(options.directory, 0o700);
+    const key = loadOrCreateKey(options.directory);
+    const sqlite = await (options.sqliteLoader ?? (() => import("node:sqlite") as Promise<SqliteModule>))();
+    const databasePath = join(options.directory, POLICY_AUDIT_DATABASE_NAME);
+    const db = new sqlite.DatabaseSync(databasePath);
+    chmodSync(databasePath, 0o600);
+    const store = new PolicyAuditStore(db, key, databasePath, options.retentionDays, options.now ?? (() => new Date()));
+    try {
+      store.initialize();
+      return store;
+    } catch (error) {
+      try { db.close(); } catch { /* preserve initialization error */ }
+      throw error;
+    }
+  }
+
+  private constructor(
+    private readonly db: Database,
+    private readonly key: Buffer,
+    private readonly databasePath: string,
+    private readonly retentionDays: number,
+    private readonly now: () => Date,
+    private closed = false,
+  ) {}
+
+  private initialize(): void {
+    this.db.exec("PRAGMA busy_timeout=75; PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL; PRAGMA foreign_keys=ON;");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL) STRICT;
+      CREATE TABLE IF NOT EXISTS seen_requests (
+        request_hash TEXT PRIMARY KEY,
+        seen_day TEXT NOT NULL
+      ) STRICT;
+      CREATE TABLE IF NOT EXISTS daily_permission_stats (
+        day TEXT NOT NULL,
+        project_hash TEXT NOT NULL,
+        surface TEXT NOT NULL,
+        signature TEXT NOT NULL,
+        bash_category TEXT NOT NULL,
+        risk TEXT NOT NULL,
+        path_class TEXT NOT NULL,
+        result TEXT NOT NULL,
+        resolution TEXT NOT NULL,
+        origin TEXT NOT NULL,
+        forwarded INTEGER NOT NULL,
+        features TEXT NOT NULL,
+        rule_fingerprint TEXT NOT NULL,
+        count INTEGER NOT NULL,
+        PRIMARY KEY (day, project_hash, surface, signature, bash_category, risk, path_class, result, resolution, origin, forwarded, features, rule_fingerprint)
+      ) STRICT;
+      CREATE INDEX IF NOT EXISTS daily_permission_stats_project_day ON daily_permission_stats(project_hash, day);
+    `);
+    const version = this.db.prepare("SELECT value FROM meta WHERE key='schema_version'").get()?.value;
+    if (version !== undefined && version !== String(POLICY_AUDIT_SCHEMA_VERSION)) {
+      throw new Error("unsupported policy audit schema version");
+    }
+    const now = this.now().toISOString();
+    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('schema_version',?)").run(String(POLICY_AUDIT_SCHEMA_VERSION));
+    this.db.prepare("INSERT OR IGNORE INTO meta(key,value) VALUES('collecting_since',?)").run(now);
+    this.secureSidecars();
+  }
+
+  private hash(kind: string, value: string): string {
+    return createHmac("sha256", this.key).update(`${kind}\0${value}`).digest("hex");
+  }
+
+  projectHash(projectPath: string): string {
+    return this.hash("project", resolve(projectPath));
+  }
+
+  ruleFingerprint(pattern: string | undefined): string {
+    return pattern ? this.hash("rule", pattern).slice(0, 16) : "none";
+  }
+
+  private retry<T>(operation: () => T): T {
+    let last: unknown;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        return operation();
+      } catch (error) {
+        last = error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (!/busy|locked/i.test(message) || attempt === 2) throw error;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10 * (attempt + 1));
+      }
+    }
+    throw last;
+  }
+
+  record(projectPath: string, event: SanitizedPermissionDecision): boolean {
+    return this.retry(() => {
+      const day = dayString(this.now());
+      this.pruneIfNeeded(day);
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        const requestHash = this.hash("request", event.requestId);
+        const inserted = this.db.prepare("INSERT OR IGNORE INTO seen_requests(request_hash,seen_day) VALUES(?,?)").run(requestHash, day);
+        if (Number(inserted.changes) === 0) {
+          this.db.exec("COMMIT");
+          return false;
+        }
+        this.db.prepare(`
+          INSERT INTO daily_permission_stats(
+            day,project_hash,surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,count
+          ) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,1)
+          ON CONFLICT DO UPDATE SET count=count+1
+        `).run(
+          day,
+          this.projectHash(projectPath),
+          event.surface,
+          event.signature,
+          event.bashCategory,
+          event.risk,
+          event.pathClass,
+          event.result,
+          event.resolution,
+          normalizeOrigin(event.origin),
+          event.forwarded ? 1 : 0,
+          event.features.join(","),
+          this.ruleFingerprint(event.matchedPattern),
+        );
+        this.db.exec("COMMIT");
+        this.secureSidecars();
+        return true;
+      } catch (error) {
+        try { this.db.exec("ROLLBACK"); } catch { /* preserve original error */ }
+        throw error;
+      }
+    });
+  }
+
+  private pruneIfNeeded(today: string): void {
+    const last = this.db.prepare("SELECT value FROM meta WHERE key='last_cleanup_day'").get()?.value;
+    if (last === today) return;
+    const cutoff = dayString(addDays(this.now(), -this.retentionDays + 1));
+    this.db.prepare("DELETE FROM daily_permission_stats WHERE day < ?").run(cutoff);
+    this.db.prepare("DELETE FROM seen_requests WHERE seen_day < ?").run(cutoff);
+    this.db.prepare("INSERT INTO meta(key,value) VALUES('last_cleanup_day',?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(today);
+  }
+
+  query(input: PolicyAuditQuery): PolicyAuditQueryResult {
+    return this.retry(() => {
+      const throughDay = dayString(this.now());
+      const fromDay = dayString(addDays(this.now(), -input.days + 1));
+      const projectClause = input.scope === "current" ? "AND project_hash = ?" : "";
+      const params: unknown[] = [fromDay];
+      if (input.scope === "current") params.push(this.projectHash(input.projectPath));
+      const rows = this.db.prepare(`
+        SELECT surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint,SUM(count) AS count
+        FROM daily_permission_stats
+        WHERE day >= ? ${projectClause}
+        GROUP BY surface,signature,bash_category,risk,path_class,result,resolution,origin,forwarded,features,rule_fingerprint
+      `).all(...params).map((row) => ({
+        surface: String(row.surface), signature: String(row.signature), bashCategory: String(row.bash_category),
+        risk: String(row.risk), pathClass: String(row.path_class), result: String(row.result),
+        resolution: String(row.resolution), origin: String(row.origin), forwarded: Number(row.forwarded) === 1,
+        features: String(row.features), ruleFingerprint: String(row.rule_fingerprint), count: Number(row.count),
+      }));
+      const collectingSince = String(this.db.prepare("SELECT value FROM meta WHERE key='collecting_since'").get()?.value ?? "unknown");
+      return { collectingSince, fromDay, throughDay, rows };
+    });
+  }
+
+  private secureSidecars(): void {
+    for (const path of [this.databasePath, `${this.databasePath}-wal`, `${this.databasePath}-shm`]) {
+      if (existsSync(path)) chmodSync(path, 0o600);
+    }
+  }
+
+  close(): void {
+    // Concurrent session_shutdown handlers must not reject a second close.
+    if (this.closed) return;
+    this.closed = true;
+    this.db.close();
+  }
+}
+
+export function defaultPolicyAuditDirectory(home: string): string {
+  return join(home, ".pi", "agent", "extensions", "pi-auto-review");
+}