pi-warden 0.71.0 → 0.74.0

package/dist/learning.js

@@ -2,10 +2,11 @@
 // Records full context with each hold and predicts outcomes using history.
 import { createHash } from "crypto";
 import { mkdirSync } from "fs";
-import { homedir } from "os";
 import { dirname, join } from "path";
+import { defaultHostDirs } from "./host-dirs.js";
+import { userConfigPath } from "./config.js";
 import { redact } from "./redact.js";
-let db;
+const dbs = new Map();
 let sqliteAvailable;
 // --- Schema (shared constant) ---
 export const HOLDS_SCHEMA = `
@@ -38,31 +39,52 @@ const NOOP_DB = {
     prepare() { return { run() { return { changes: 0, lastInsertRowid: 0 }; }, get() { return undefined; }, all() { return []; } }; },
     pragma() { },
 };
-async function getDb() {
-    if (db)
-        return db;
-    if (sqliteAvailable === false)
-        return NOOP_DB;
+/** Open one connection; a failure is remembered per path so later calls neither warn again nor retry forever. */
+async function openDb(dbPath) {
+    let opened;
     try {
-        const { DatabaseSync } = await import("node:sqlite");
+        // Static import cannot work: node:sqlite is flagged experimental and loads lazily so a missing
+        // or broken build of it disables learning features instead of failing the whole process.
+        const sqlite = await import("node:sqlite").catch(err => ({ importFailed: err }));
+        if ("importFailed" in sqlite) {
+            sqliteAvailable = false;
+            console.warn("pi-warden: node:sqlite unavailable, learning features disabled:", sqlite.importFailed);
+            return NOOP_DB;
+        }
+        const { DatabaseSync } = sqlite;
         sqliteAvailable = true;
-        const dbPath = process.env.PI_WARDEN_DB ?? join(homedir(), ".pi", "agent", "pi-warden", "holds.db");
         // DatabaseSync does not create parent directories; on a fresh machine the folder may not exist yet.
         mkdirSync(dirname(dbPath), { recursive: true, mode: 0o700 });
-        db = new DatabaseSync(dbPath);
-        db.exec("PRAGMA journal_mode = WAL");
-        db.exec("PRAGMA busy_timeout = 10000");
-        return db;
+        opened = new DatabaseSync(dbPath);
+        opened.exec("PRAGMA journal_mode = WAL");
+        opened.exec("PRAGMA busy_timeout = 10000");
+        return opened;
     }
     catch (err) {
-        sqliteAvailable = false;
-        console.warn("pi-warden: node:sqlite unavailable, learning features disabled:", err);
+        // Import failures are handled above; this is a path open or PRAGMA failure for this path only.
+        // Close the half-opened handle and leave the resolved NOOP promise cached: one warning,
+        // and later calls neither reopen nor retry an unusable file.
+        try {
+            opened?.close();
+        }
+        catch { /* already closed */ }
+        console.warn(`pi-warden: could not open ${dbPath}:`, err);
         return NOOP_DB;
     }
 }
-export async function initSchema(retentionDays = 365) {
+/** One connection per resolved path; concurrent first calls share one open. */
+async function getDb(dirs = defaultHostDirs()) {
+    const dbPath = process.env.PI_WARDEN_DB ?? join(dirname(userConfigPath(dirs)), "holds.db");
+    if (sqliteAvailable === false)
+        return NOOP_DB;
+    let opening = dbs.get(dbPath);
+    if (!opening)
+        dbs.set(dbPath, opening = openDb(dbPath));
+    return opening;
+}
+export async function initSchema(retentionDays = 365, dirs = defaultHostDirs()) {
     try {
-        const d = await getDb();
+        const d = await getDb(dirs);
         d.exec(HOLDS_SCHEMA);
         // Migrate: add columns that may be missing from older databases.
         try {
@@ -135,8 +157,8 @@ export function toHoldRecord(item, projectRoot, ctx) {
     return result;
 }
 // --- Recording ---
-export async function recordHold(hold) {
-    const d = await getDb();
+export async function recordHold(hold, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     const hash = signatureHash(hold.tool, hold.scores);
     const stmt = d.prepare(`
     INSERT INTO holds
@@ -148,9 +170,9 @@ export async function recordHold(hold) {
     const result = stmt.run(hold.timestamp, hold.projectRoot, hold.tool, hash, hold.commandPreview, hold.task ?? null, hold.plan ?? null, hold.contextSummary ?? null, hold.precedingActions ?? null, JSON.stringify(hold.scores), hold.level, hold.held ? 1 : 0, JSON.stringify(hold.reasons), hold.agentReason ?? null, hold.confidence ?? null);
     return Number(result.lastInsertRowid);
 }
-export async function recordOutcome(id, outcome) {
+export async function recordOutcome(id, outcome, dirs = defaultHostDirs()) {
     try {
-        (await getDb()).prepare("UPDATE holds SET outcome = ?, outcome_at = ? WHERE id = ?").run(outcome, Date.now(), id);
+        (await getDb(dirs)).prepare("UPDATE holds SET outcome = ?, outcome_at = ? WHERE id = ?").run(outcome, Date.now(), id);
     }
     catch (err) {
         console.warn("pi-warden: could not record hold outcome:", err);
@@ -158,15 +180,15 @@ export async function recordOutcome(id, outcome) {
 }
 // --- Querying ---
 /** Query holds by project and held value. Used by tests and future analytics. */
-export async function queryHoldsForProject(projectRoot, options) {
-    const d = await getDb();
+export async function queryHoldsForProject(projectRoot, options, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     if (options?.held !== undefined) {
         return d.prepare("SELECT id, tool, held, outcome, command_preview FROM holds WHERE project_root = ? AND held = ? ORDER BY timestamp").all(projectRoot, options.held ? 1 : 0);
     }
     return d.prepare("SELECT id, tool, held, outcome, command_preview FROM holds WHERE project_root = ? ORDER BY timestamp").all(projectRoot);
 }
-export async function holdStats(projectRoot) {
-    const d = await getDb();
+export async function holdStats(projectRoot, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     const held = d.prepare(`SELECT
       COUNT(*) AS total,
       COUNT(CASE WHEN outcome IN ('approved','declined','replanned') THEN 1 END) AS labeled,
@@ -194,8 +216,8 @@ export async function holdStats(projectRoot) {
         newest: held.newest ?? 0,
     };
 }
-export async function querySmartHistory(tool, scores, projectRoot) {
-    const d = await getDb();
+export async function querySmartHistory(tool, scores, projectRoot, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     const hash = signatureHash(tool, scores);
     const exact = d.prepare(`
     SELECT task, plan, outcome, scores, agent_reason, timestamp
@@ -236,8 +258,8 @@ export function calculateSmartConfidence(history) {
     };
 }
 // --- Integration ---
-export async function shouldSkipHold(tool, scores, projectRoot) {
-    const history = await querySmartHistory(tool, scores, projectRoot);
+export async function shouldSkipHold(tool, scores, projectRoot, dirs = defaultHostDirs()) {
+    const history = await querySmartHistory(tool, scores, projectRoot, dirs);
     const { confidence, reason } = calculateSmartConfidence(history);
     const isDestructive = scores.reasons.some(r => r.startsWith("destructive:"));
     if (isDestructive)
@@ -248,8 +270,8 @@ export async function shouldSkipHold(tool, scores, projectRoot) {
     return { skip: false, confidence, reason };
 }
 /** Analyze hold outcomes to suggest threshold adjustments. */
-export async function analyzeThresholds(projectRoot) {
-    const d = await getDb();
+export async function analyzeThresholds(projectRoot, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     const adjustments = [];
     // Analyze action guard: look at holds vs approvals
     const actionHolds = d.prepare(`
@@ -295,8 +317,8 @@ export async function analyzeThresholds(projectRoot) {
     }
     return adjustments;
 }
-export async function analyzePatterns(projectRoot) {
-    const d = await getDb();
+export async function analyzePatterns(projectRoot, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     const insights = [];
     // Get pattern outcomes
     const patterns = d.prepare(`
@@ -340,9 +362,9 @@ export async function analyzePatterns(projectRoot) {
     return insights.sort((a, b) => b.falsePositiveRate - a.falsePositiveRate);
 }
 /** Generate recommendations based on learning data. */
-export async function generateRecommendations(projectRoot) {
+export async function generateRecommendations(projectRoot, dirs = defaultHostDirs()) {
     const recommendations = [];
-    const thresholdAdjustments = await analyzeThresholds(projectRoot);
+    const thresholdAdjustments = await analyzeThresholds(projectRoot, dirs);
     for (const adj of thresholdAdjustments) {
         if (adj.confidence > 0.5) {
             recommendations.push({
@@ -352,7 +374,7 @@ export async function generateRecommendations(projectRoot) {
             });
         }
     }
-    const patternInsights = await analyzePatterns(projectRoot);
+    const patternInsights = await analyzePatterns(projectRoot, dirs);
     for (const insight of patternInsights.slice(0, 3)) {
         if (insight.falsePositiveRate > 0.6) {
             recommendations.push({
@@ -368,8 +390,8 @@ export async function generateRecommendations(projectRoot) {
     });
 }
 /** Analyze steer effectiveness from hold outcomes. */
-export async function analyzeSteerEffectivenessReport(projectRoot) {
-    const d = await getDb();
+export async function analyzeSteerEffectivenessReport(projectRoot, dirs = defaultHostDirs()) {
+    const d = await getDb(dirs);
     const suggestions = [];
     // Get steer outcomes (inferred from hold outcomes)
     const steerOutcomes = d.prepare(`

package/dist/loops.d.ts

@@ -1,3 +1,4 @@
+import type { HostDirs } from "./host-dirs.js";
 export declare const LOOP_CHARS = 160;
 /** Open loops shown in the appendix, the reminder, and the resume message. */
 export declare const LOOPS_SHOWN = 8;
@@ -25,7 +26,7 @@ export declare function emptyLoopStore(): LoopStore;
  * One file per session, in a folder per project: the working directory's hash keeps another project's session with the
  * same id apart, and the id keeps another session of this project apart.
  */
-export declare function loopsPath(cwd: string, session: string): string;
+export declare function loopsPath(cwd: string, session: string, dirs?: HostDirs): string;
 /** A missing file is an empty store; an unreadable or malformed one throws, so a write never replaces loops it could not read. */
 export declare function readLoops(path: string): Promise<LoopStore>;
 /** Written whole to a temporary file and renamed, so a crash never leaves half a file. */

package/dist/loops.js

@@ -10,6 +10,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { serialize, writeFileAtomic } from "./atomic.js";
 import { userConfigPath } from "./config.js";
+import { defaultHostDirs } from "./host-dirs.js";
 import { redact } from "./redact.js";
 export const LOOP_CHARS = 160;
 /** Open loops shown in the appendix, the reminder, and the resume message. */
@@ -25,9 +26,9 @@ export function emptyLoopStore() {
  * One file per session, in a folder per project: the working directory's hash keeps another project's session with the
  * same id apart, and the id keeps another session of this project apart.
  */
-export function loopsPath(cwd, session) {
+export function loopsPath(cwd, session, dirs = defaultHostDirs()) {
     const project = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
-    return join(dirname(userConfigPath()), "loops", project, `${session.replace(/[^\w.-]/g, "_")}.json`);
+    return join(dirname(userConfigPath(dirs)), "loops", project, `${session.replace(/[^\w.-]/g, "_")}.json`);
 }
 const isLoop = (value) => {
     const loop = value;

package/dist/panel.d.ts

@@ -1,5 +1,6 @@
 import type { Component, TuiMouseEvent, TuiMouseEventResult } from "@earendil-works/pi-tui";
 import type { WardenConfig } from "./config.js";
+import type { HostDirs } from "./host-dirs.js";
 import type { Trace } from "./trace.js";
 import type { ThemeLike } from "./widget.js";
 export interface PanelActions {
@@ -69,6 +70,7 @@ export declare class ConfigPanel implements Component {
     private readonly theme;
     private readonly actions;
     private readonly requestRender;
+    private readonly dirs;
     focused: boolean;
     private cursor;
     private scroll;
@@ -77,7 +79,7 @@ export declare class ConfigPanel implements Component {
     private editBuffer;
     private readonly edits;
     private readonly entries;
-    constructor(config: WardenConfig, theme: ThemeLike, actions: PanelActions, requestRender: () => void);
+    constructor(config: WardenConfig, theme: ThemeLike, actions: PanelActions, requestRender: () => void, dirs?: HostDirs);
     invalidate(): void;
     private lines;
     render(width: number): string[];
@@ -89,4 +91,5 @@ export declare class ConfigPanel implements Component {
 }
 export declare function openConfigPanel(ui: PanelUi, config: WardenConfig, options?: {
     width?: string | number;
+    dirs?: HostDirs;
 }): PanelController;

package/dist/panel.js

@@ -1,5 +1,6 @@
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { applyUserOverrides, defaultConfig, readUserConfig, writeUserConfig } from "./config.js";
+import { defaultHostDirs } from "./host-dirs.js";
 import { LEVEL_COLOR, parseVerdictLine, renderSegment } from "./widget.js";
 /**
  * Sidebar listing the trace newest-first, live-updating while open. It opens without taking keyboard input: the editor
@@ -169,7 +170,8 @@ export function openTracePanel(ui, trace, options = {}) {
     }, {
         overlay: true,
         overlayOptions: { anchor: "right-center", width: options.width ?? "40%", minWidth: 44, maxHeight: "100%", nonCapturing: true },
-        onHandle: (handle) => { unfocus = () => handle.unfocus(); },
+        // A handle without `unfocus` belongs to a host whose overlays always capture input; close instead.
+        onHandle: (handle) => { unfocus = typeof handle.unfocus === "function" ? () => handle.unfocus() : () => close(); },
     });
     return { closed, close: () => close(), built: () => built };
 }
@@ -195,6 +197,7 @@ export class ConfigPanel {
     theme;
     actions;
     requestRender;
+    dirs;
     focused = false;
     cursor = 0;
     scroll = 0;
@@ -203,11 +206,12 @@ export class ConfigPanel {
     editBuffer = "";
     edits = new Map();
     entries;
-    constructor(config, theme, actions, requestRender) {
+    constructor(config, theme, actions, requestRender, dirs = defaultHostDirs()) {
         this.config = config;
         this.theme = theme;
         this.actions = actions;
         this.requestRender = requestRender;
+        this.dirs = dirs;
         this.entries = flattenConfig(config);
     }
     invalidate() { }
@@ -369,7 +373,7 @@ export class ConfigPanel {
     save() {
         if (this.edits.size === 0)
             return;
-        const raw = readUserConfig();
+        const raw = readUserConfig(this.dirs);
         const obj = (typeof raw === "object" && raw !== null && !Array.isArray(raw)) ? raw : {};
         for (const [path, value] of this.edits) {
             const keys = path.split(".");
@@ -382,7 +386,7 @@ export class ConfigPanel {
             }
             current[keys.at(-1)] = value;
         }
-        writeUserConfig(obj);
+        writeUserConfig(obj, this.dirs);
         this.edits.clear();
     }
 }
@@ -391,7 +395,7 @@ export function openConfigPanel(ui, config, options = {}) {
     let unfocus = () => { };
     const closed = ui.custom((tui, theme, _keybindings, done) => {
         close = () => done();
-        const panel = new ConfigPanel(config, theme, { close, unfocus: () => unfocus() }, () => tui.requestRender());
+        const panel = new ConfigPanel(config, theme, { close, unfocus: () => unfocus() }, () => tui.requestRender(), options.dirs);
         const rows = tui.terminal?.rows;
         if (typeof rows === "number")
             panel.setViewport(rows - 2);
@@ -399,7 +403,8 @@ export function openConfigPanel(ui, config, options = {}) {
     }, {
         overlay: true,
         overlayOptions: { anchor: "right-center", width: options.width ?? "40%", minWidth: 44, maxHeight: "100%", nonCapturing: true },
-        onHandle: (handle) => { unfocus = () => handle.unfocus(); },
+        // A handle without `unfocus` belongs to a host whose overlays always capture input; close instead.
+        onHandle: (handle) => { unfocus = typeof handle.unfocus === "function" ? () => handle.unfocus() : () => close(); },
     });
     return { closed, close: () => close() };
 }

package/dist/prefs.d.ts

@@ -184,7 +184,7 @@ export interface PrefsStore {
     forgotten: Forgotten[];
 }
 export declare function emptyPrefsStore(): PrefsStore;
-export declare function prefsStorePath(project: string): string;
+export declare function prefsStorePath(project: string, dirs?: import("./host-dirs.js").HostDirs): string;
 /**
  * A missing file is an empty store. An unreadable or malformed one throws: without the forgotten list, a group the
  * user dropped could reach the agent again, so the caller injects nothing and says why.

package/dist/prefs.js

@@ -14,6 +14,7 @@ import { open, readdir, readFile, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { serialize, writeFileAtomic } from "./atomic.js";
 import { userConfigPath } from "./config.js";
+import { defaultHostDirs } from "./host-dirs.js";
 import { redact } from "./redact.js";
 /**
  * Short automated sessions fill a project's directory quickly: on real data the newest 50 sessions covered three to six
@@ -502,9 +503,9 @@ export async function scanPreferences(options) {
 export function emptyPrefsStore() {
     return { lessons: [], confirmations: [], forgotten: [] };
 }
-export function prefsStorePath(project) {
+export function prefsStorePath(project, dirs = defaultHostDirs()) {
     const hash = createHash("sha256").update(project).digest("hex").slice(0, 12);
-    return join(dirname(userConfigPath()), "prefs", `${hash}.json`);
+    return join(dirname(userConfigPath(dirs)), "prefs", `${hash}.json`);
 }
 const isRecord = (value) => typeof value === "object" && value !== null && typeof value.session === "string" && typeof value.at === "number";
 const isLesson = (value) => typeof value === "object" && value !== null && typeof value.text === "string" && Array.isArray(value.records) && value.records.every(isRecord);

package/dist/rules-audit.d.ts

@@ -0,0 +1,208 @@
+import type { Judge } from "pi-typesafe";
+import type { RulesConfig } from "./config.js";
+import type { RuleSet, RulesVerdict } from "./rules.js";
+/**
+ * `/warden rules audit` and `/warden bench`: two plain functions over the rules guard.
+ *
+ * The audit judges existing files against the project rules as if each had just been written, one `write` request per
+ * file. Nothing leaves the machine without the confirm dialog (or `--yes` in a headless run), the results never reach
+ * the rules log, and the only file written is the Markdown copy under `.pi-warden/`. The bench measures what one of
+ * those requests costs on this machine with a fixed built-in sample, so no project content is sent for it at all.
+ */
+/** Files the audit judges unless `--max` says otherwise. */
+export declare const AUDIT_DEFAULT_MAX = 50;
+/** Requests in flight at once; small so a big audit cannot burst the backend. */
+export declare const AUDIT_CONCURRENCY = 4;
+/** Source files the discovery walk collects before it stops; the cap counts what it found. */
+export declare const AUDIT_DISCOVERY_MAX = 5000;
+export declare const AUDIT_REPORT_FILE = ".pi-warden/rules-audit.md";
+export declare const RULES_AUDIT_USAGE = "Usage: /warden rules audit [paths...] [--max N] [--yes], where N is a positive integer (default 50) and paths default to the project.";
+export declare const BENCH_USAGE = "Usage: /warden bench [--runs N], where N is a positive integer (default 10).";
+export interface RulesAuditArgs {
+    /** Project-relative paths to audit; `["."]` when none were given. */
+    paths: string[];
+    max: number;
+    yes: boolean;
+    error?: string;
+}
+export declare function parseRulesAuditArgs(tokens: readonly string[]): RulesAuditArgs;
+export interface BenchArgs {
+    runs: number;
+    error?: string;
+}
+export declare function parseBenchArgs(tokens: readonly string[]): BenchArgs;
+export interface AuditFilePlan {
+    /** Project-relative paths to judge, in sorted order, capped at `max`. */
+    files: string[];
+    /** Files that passed every filter (git, `rules.exclude`, `rules.skip`, and at least one applicable rule). */
+    matched: number;
+    /** Matched files left out at the cap. */
+    leftOut: number;
+    /** Given paths that are not a file or directory inside the project. */
+    missing: string[];
+}
+/**
+ * The source files under `paths` the audit will judge: found by `discoverSourceFiles`, inside the project, not ignored
+ * by git, not kept out by `rules.exclude` or `rules.skip`, and with at least one rule that applies to them. Capped in
+ * sorted order so the same command judges the same files twice.
+ */
+export declare function collectAuditFiles(cwd: string, paths: readonly string[], set: RuleSet | undefined, config: RulesConfig, max: number): AuditFilePlan;
+export interface RulesAuditFileResult {
+    /** Project-relative path. */
+    path: string;
+    verdict: RulesVerdict;
+}
+export interface RulesAuditRow {
+    id: string;
+    name: string;
+    /** Files whose request asked about this rule. */
+    judged: number;
+    /** Files where the rule scored at or above its cutoff. */
+    flagged: number;
+    /** Mean P(violation) over the files judged. */
+    mean: number;
+}
+export interface RulesAuditOutcome {
+    paths: string[];
+    max: number;
+    /** Files selected for judgment. */
+    selected: number;
+    judged: number;
+    leftOut: number;
+    missing: string[];
+    /** Selected files that could not be read or were empty. */
+    unreadable: string[];
+    /** Files whose judgment came back as an error. */
+    errors: string[];
+    results: RulesAuditFileResult[];
+    rows: RulesAuditRow[];
+    /** Files with at least one finding. */
+    flagged: number;
+    sources: string[];
+    /** Distinct rules asked across the audit. */
+    rules: number;
+    aggregate: boolean;
+    reportPath: string;
+    elapsedMs: number;
+}
+export type RulesAuditResult = {
+    status: "no-judge";
+} | {
+    status: "no-files";
+    reason: string;
+} | {
+    status: "needs-yes";
+    files: number;
+    leftOut: number;
+} | {
+    status: "cancelled";
+} | {
+    status: "done";
+    outcome: RulesAuditOutcome;
+};
+export interface RulesAuditOptions {
+    cwd: string;
+    paths: readonly string[];
+    max: number;
+    /** Headless runs pass `--yes`; without it and without a dialog nothing is sent. */
+    yes: boolean;
+    config: RulesConfig;
+    set: RuleSet | undefined;
+    judge?: Judge | undefined;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    /** Where the samples go, named in the confirm dialog. */
+    destination: string;
+    confirm?: ((title: string, body: string) => boolean | Promise<boolean>) | undefined;
+}
+/**
+ * One `write` request per selected file, at most AUDIT_CONCURRENCY at a time, after the confirm dialog (or `--yes`).
+ * With no judge nothing is sent and no dialog is shown. The Markdown copy is written to `AUDIT_REPORT_FILE`; the rules
+ * log is never touched.
+ */
+export declare function runRulesAudit(options: RulesAuditOptions): Promise<RulesAuditResult>;
+/** The per-rule table body, flagged rules first. */
+export declare function formatRulesAuditRows(rows: readonly RulesAuditRow[]): string;
+export interface RulesAuditFlag {
+    name: string;
+    score: number;
+}
+export interface RulesAuditFileFlags {
+    path: string;
+    findings: RulesAuditFlag[];
+    soft: RulesAuditFlag[];
+}
+/** Files with findings, worst first (most findings, then the strongest score). */
+export declare function flaggedAuditFiles(results: readonly RulesAuditFileResult[]): RulesAuditFileFlags[];
+/** One line per file, rule names with scores indented under the path. */
+export declare function formatRulesAuditFiles(results: readonly RulesAuditFileResult[]): string;
+/** The terminal output: summary, the table by rule, the file list, and where the Markdown copy went. */
+export declare function formatRulesAudit(outcome: RulesAuditOutcome): string;
+/** The Markdown copy of one audit run. */
+export declare function rulesAuditMarkdown(outcome: RulesAuditOutcome, date?: Date): string;
+/** Write the Markdown copy and return the path it went to. */
+export declare function writeRulesAuditReport(cwd: string, markdown: string): string;
+/** One row per rule asked anywhere in the audit: files judged, files flagged, mean score; flagged first. */
+export declare function ruleAuditRows(results: readonly RulesAuditFileResult[]): RulesAuditRow[];
+/**
+ * The one fixed sample the bench judges. It is built in, so no project content is sent for a bench run; only the
+ * active rule text travels with it.
+ */
+export declare const BENCH_SAMPLE: {
+    path: string;
+    content: string;
+};
+/** The session counters a bench run diffs; what pi-typesafe's `getUsage()` returns. */
+export interface BenchUsage {
+    requestsStarted: number;
+    inputTokens: number;
+    outputTokens: number;
+    estimatedUsd: number;
+}
+export interface BenchOptions {
+    runs: number;
+    cwd: string;
+    config: RulesConfig;
+    set: RuleSet | undefined;
+    judge?: Judge | undefined;
+    getUsage?: (() => BenchUsage) | undefined;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+    /** Clock for the latency measurements; injected by tests. */
+    now?: () => number;
+}
+export type BenchResult = {
+    status: "no-judge";
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "done";
+    runs: number;
+    /** Rules asked per check. */
+    asked: number;
+    aggregate: boolean;
+    /** Checks with at least one finding. */
+    flagged: number;
+    /** Checks that came back as an error. */
+    errors: number;
+    /** Requests sent, from `getUsage()`; the checks themselves without it. */
+    requests: number;
+    p50: number;
+    p95: number;
+    meanInputTokens?: number;
+    costPerCheck?: number;
+    costPer100?: number;
+};
+/** Nearest-rank percentile of a sorted, non-empty list of numbers. */
+export declare function percentile(sorted: readonly number[], p: number): number;
+/**
+ * Judge the built-in sample `runs` times against the active rules, one request at a time so the latency numbers mean
+ * something, and report what the checks cost on this machine. With no judge nothing is sent; a sample the rules keep
+ * out (`rules.exclude`, `rules.skip`) is reported and never sent either.
+ */
+export declare function runBench(options: BenchOptions): Promise<BenchResult>;
+/** The bench output: the numbers, and the line that says no project content was sent. */
+export declare function formatBench(result: Extract<BenchResult, {
+    status: "done";
+}>): string;