failproofai 0.0.10 → 0.0.11-beta.10

package/src/audit/detectors/prefer-edit-over-sed-awk.ts

@@ -0,0 +1,27 @@
+import type { Detector } from "../types";
+
+/** In-place edits with `sed -i` or `awk … > file` that should have been done
+ *  with the Edit tool. */
+export const preferEditOverSedAwk: Detector = {
+  name: "prefer-edit-over-sed-awk",
+  description: "Bash `sed -i`/`awk` in-place edits — use Edit.",
+  category: "Wasteful",
+  severity: "info",
+  displayTitle: "Used sed -i or awk for an in-place edit",
+  impact: "Edit tool is safer and produces a diff the agent can verify.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string") return null;
+    const cmd = command.trim();
+    // `sed -i ...` (GNU/macOS) or `sed -i'.bak' ...` (BSD-style)
+    if (/(?:^|\s|;|&&|\|\|)sed\b[^|]*\s-i(?=\b|['"])/.test(cmd)) {
+      return { example: cmd };
+    }
+    // `awk '...' file > out` or `awk '...' file > file` (in-place via redirection)
+    if (/(?:^|\s|;|&&|\|\|)awk\b[^|]*\s>\s*\S+/.test(cmd) && !/\|/.test(cmd)) {
+      return { example: cmd };
+    }
+    return null;
+  },
+};

package/src/audit/detectors/prefer-write-over-heredoc.ts

@@ -0,0 +1,36 @@
+import type { Detector } from "../types";
+
+/** `cat << EOF > file` heredoc patterns or `echo … > file` writing multi-line
+ *  content. The Write tool is the right answer. */
+export const preferWriteOverHeredoc: Detector = {
+  name: "prefer-write-over-heredoc",
+  description: "Bash heredoc / `echo > file` writing multi-line content — use Write.",
+  category: "Wasteful",
+  severity: "info",
+  displayTitle: "Used heredoc / `echo > file` to write a multi-line file",
+  impact: "Write tool handles escaping and is verifiable.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string") return null;
+    const cmd = command;
+    // Heredoc redirected to a file IMMEDIATELY after the delimiter:
+    //   `cat <<'EOF' > path`   ← match (heredoc opens AND redirects in one step)
+    //   `cat <<EOF` inside `$(...)` ← skip (heredoc captured by command substitution,
+    //                                   later `> file` is unrelated)
+    // The redirect must appear before the next whitespace/newline that ends the
+    // heredoc opener line — otherwise it's a body or downstream redirect.
+    // Heredoc delimiters are case-sensitive but `EOF`, `eof`, `Eof`, `MARKER`
+    // and digits-after-letter are all valid; match any letter/digit/underscore.
+    if (/<<-?\s*['"]?[A-Za-z_][A-Za-z0-9_]*['"]?\s*>\s*\S/.test(cmd)) {
+      const summary = cmd.replace(/\s+/g, " ").trim().slice(0, 160);
+      return { example: summary };
+    }
+    // `echo "multi\nline" > file` or `printf "..." > file` with embedded newlines.
+    if (/(?:^|\s|;|&&|\|\|)(?:echo|printf)\s+["'][^"']*\n[^"']*["']\s*>\s*\S/.test(cmd)) {
+      const summary = cmd.replace(/\s+/g, " ").trim().slice(0, 160);
+      return { example: summary };
+    }
+    return null;
+  },
+};

package/src/audit/detectors/redundant-cd-cwd.ts

@@ -0,0 +1,28 @@
+import type { Detector } from "../types";
+
+/** Bash command starting with `cd <absolute-path> && …` where the absolute
+ *  path equals (or is the same realpath as) the session's cwd. The agent's
+ *  shell already runs in cwd — the prefix is pure waste. Explicitly called
+ *  out in the Claude Code system prompt for git commands. */
+export const redundantCdCwd: Detector = {
+  name: "redundant-cd-cwd",
+  description:
+    "Bash commands prefixed with `cd <cwd> && …` even though commands already run in cwd.",
+  category: "Wasteful",
+  severity: "info",
+  displayTitle: "Prepended cd <cwd> before commands",
+  impact: "Pure waste — your agent's shell already runs in `cwd`.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string" || !event.cwd) return null;
+    const trimmed = command.trimStart();
+    const match = /^cd\s+(?:"([^"]+)"|'([^']+)'|(\S+))\s*&&\s*([\s\S]+)$/.exec(trimmed);
+    if (!match) return null;
+    const path = (match[1] ?? match[2] ?? match[3] ?? "").replace(/\/+$/, "");
+    const cwd = event.cwd.replace(/\/+$/, "");
+    if (path !== cwd) return null;
+    const rest = match[4].trim();
+    return { example: `cd ${path} && ${rest}` };
+  },
+};

package/src/audit/detectors/reread-after-edit.ts

@@ -0,0 +1,58 @@
+import type { Detector, DetectorSessionState } from "../types";
+
+const STATE_KEY = "rereadAfterEdit";
+const WINDOW = 5;
+
+interface RereadState {
+  /** Map of file_path → number of remaining tool-calls in which a Read should
+   *  trigger this detector. Decremented every tool event; deleted at 0. */
+  countdown: Map<string, number>;
+}
+
+function getState(state: DetectorSessionState): RereadState {
+  let s = state[STATE_KEY] as RereadState | undefined;
+  if (!s) {
+    s = { countdown: new Map() };
+    state[STATE_KEY] = s;
+  }
+  return s;
+}
+
+/** When Edit or Write lands on file_path, then a subsequent Read of the same
+ *  file_path within N tool calls is wasteful — the editor already returned the
+ *  updated content. Explicitly called out in the Claude system prompt. */
+export const rereadAfterEdit: Detector = {
+  name: "reread-after-edit",
+  description: "Read of a file that was just Edit'd or Write'n in the same session.",
+  category: "Wasteful",
+  severity: "info",
+  displayTitle: "Re-read a file it just edited",
+  impact: "Edit/Write already returned the updated content; the second Read is wasted tokens.",
+  detect(event, sessionState) {
+    const state = getState(sessionState);
+    const filePath = (event.toolInput as { file_path?: unknown }).file_path;
+    const pathStr = typeof filePath === "string" ? filePath : null;
+
+    // Tick down every existing countdown.
+    for (const [key, n] of state.countdown) {
+      if (n <= 1) state.countdown.delete(key);
+      else state.countdown.set(key, n - 1);
+    }
+
+    if (!pathStr) return null;
+
+    if (event.toolName === "Edit" || event.toolName === "Write") {
+      state.countdown.set(pathStr, WINDOW);
+      return null;
+    }
+
+    if (event.toolName === "Read") {
+      if (state.countdown.has(pathStr)) {
+        state.countdown.delete(pathStr); // count once per edit-then-read pair
+        return { example: `Read ${pathStr} immediately after Edit/Write` };
+      }
+    }
+
+    return null;
+  },
+};

package/src/audit/detectors/sleep-polling-loop.ts

@@ -0,0 +1,34 @@
+import type { Detector } from "../types";
+
+const SLEEP_THRESHOLD_SECONDS = 30;
+
+/** Bash `sleep N` where N ≥ 30 (busy polling), or `while …; sleep …; done`. */
+export const sleepPollingLoop: Detector = {
+  name: "sleep-polling-loop",
+  description: "Bash long `sleep` or while-sleep polling loops.",
+  category: "Wasteful",
+  severity: "info",
+  displayTitle: "Used a long sleep or while-sleep polling loop",
+  impact: "Burns wall-clock; better to wait for an explicit signal.",
+  detect(event) {
+    if (event.toolName !== "Bash") return null;
+    const command = (event.toolInput as { command?: unknown }).command;
+    if (typeof command !== "string") return null;
+    const cmd = command;
+    // while-sleep loop
+    if (/\bwhile\b[\s\S]*?\bsleep\b[\s\S]*?\bdone\b/.test(cmd)) {
+      return { example: cmd.replace(/\s+/g, " ").trim().slice(0, 160) };
+    }
+    // Standalone long sleep. parseFloat so `sleep 0.5m` (= 30s) isn't dropped.
+    const match = /\bsleep\s+(\d+(?:\.\d+)?)(m|h|d)?\b/.exec(cmd);
+    if (match) {
+      const n = parseFloat(match[1]);
+      const unit = match[2] ?? "s";
+      const seconds = unit === "m" ? n * 60 : unit === "h" ? n * 3600 : unit === "d" ? n * 86400 : n;
+      if (seconds >= SLEEP_THRESHOLD_SECONDS) {
+        return { example: cmd.replace(/\s+/g, " ").trim().slice(0, 160) };
+      }
+    }
+    return null;
+  },
+};

package/src/audit/features.ts

@@ -0,0 +1,314 @@
+/**
+ * Behavioural feature layer for the audit dashboard.
+ *
+ * Both the archetype classifier (`archetypes.ts`) and the score derivation
+ * (`scoring.ts`) read from the *same* derived features so they can never
+ * drift. Everything here is a pure function of `AuditResult` (+ an optional
+ * seed string) — no I/O, no clock, no `Math.random()`. Given the same input,
+ * every output is byte-identical on every run.
+ *
+ * Design goals (see the audit redesign):
+ *   1. All 8 personas reachable. Five are mapped by *which* faults dominate
+ *      (`SIGNAL_MAP`); three are relational — `precision` (low fault rate),
+ *      `architect` (faults are over-verification), `goldfish` (scattered).
+ *   2. No systemic skew. Ranking is by *lift = observed-share ÷ baseline-share*
+ *      where the baseline is the EMPIRICAL firing share of each cluster for a
+ *      typical agent (see BASELINE_SHARE / EMPIRICAL_FIRING_SHARE), not the
+ *      catalog weight share. This is what stops ambient, high-firing clusters
+ *      (explorer, architect) from collapsing the whole population onto one
+ *      persona: a cluster wins only when it fires *more than typical*, not
+ *      merely often. `block-read-outside-cwd` is excluded from SIGNAL_MAP
+ *      entirely — it is off by default and fires on ubiquitous ambient reads.
+ *   3. Deterministic personalisation. A `fingerprint` hash of the rounded
+ *      behaviour vector seeds tie-breaks and copy-variant selection, so two
+ *      different agents that land on the same primary still look distinct,
+ *      while the same agent is always identical.
+ */
+import type { AuditResult } from "./types";
+import type { ArchetypeKey } from "./archetypes";
+
+/** djb2-style hash. Stable across renders/processes, no crypto needed.
+ *  Lives here (not archetypes.ts) so the feature layer has no import cycle. */
+export function hashSeed(s: string): number {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = ((h << 5) + h + s.charCodeAt(i)) | 0;
+  return h >>> 0;
+}
+
+/** Strip the `failproofai/` namespace so map keys match the bare policy name. */
+export function shortName(name: string): string {
+  const slash = name.indexOf("/");
+  return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+/** All eight archetype keys, including the two relational ones. */
+export const ALL_ARCHETYPE_KEYS: ArchetypeKey[] = [
+  "optimist", "cowboy", "explorer", "goldfish",
+  "architect", "precision", "hammer", "ghost",
+];
+
+/**
+ * Personas that receive direct signal mapping. `precision` and `goldfish`
+ * are NOT here — they are derived from the *shape* of the distribution, not
+ * from any single policy. `architect` is mapped (it owns the two "caution"
+ * detectors) but is primarily reached via its ratio rule.
+ */
+export const MAPPABLE_KEYS: ArchetypeKey[] = [
+  "cowboy", "explorer", "ghost", "optimist", "hammer", "architect",
+];
+
+/** Active-fault personas ranked by lift in the classifier's argmax step. */
+export const ACTIVE_FAULT_KEYS: ArchetypeKey[] = [
+  "cowboy", "explorer", "ghost", "optimist", "hammer",
+];
+
+/** The two detectors that define "the paranoid architect" — pure
+ *  over-verification. When these dominate an agent's signal it is classified
+ *  architect regardless of raw weight. */
+export const ARCHITECT_CAUTION_SIGNALS = new Set(["reread-after-edit", "redundant-cd-cwd"]);
+
+/**
+ * Mapping from policy/detector short-name → which archetype its hits feed,
+ * and how heavily (intensity within the cluster). Every one of the 39 builtin
+ * policies and 8 audit-only detectors maps exactly once — no overlaps, full
+ * coverage. Weights express *severity within* a persona; cross-persona
+ * fairness is handled later by lift normalisation, not by these numbers.
+ */
+export const SIGNAL_MAP: Record<string, { archetype: ArchetypeKey; weight: number }> = {
+  // ── cowboy ── destructive / forceful / bypasses guardrails (20) ───────────
+  "block-rm-rf":               { archetype: "cowboy", weight: 2.0 },
+  "block-failproofai-commands":{ archetype: "cowboy", weight: 2.0 },
+  "block-sudo":                { archetype: "cowboy", weight: 1.5 },
+  "block-curl-pipe-sh":        { archetype: "cowboy", weight: 1.5 },
+  "block-force-push":          { archetype: "cowboy", weight: 1.5 },
+  "block-push-master":         { archetype: "cowboy", weight: 1.5 },
+  "block-work-on-main":        { archetype: "cowboy", weight: 1.2 },
+  "warn-destructive-sql":      { archetype: "cowboy", weight: 1.5 },
+  "warn-schema-alteration":    { archetype: "cowboy", weight: 1.0 },
+  "git-commit-no-verify":      { archetype: "cowboy", weight: 1.5 },
+  "warn-git-amend":            { archetype: "cowboy", weight: 0.8 },
+  "warn-git-stash-drop":       { archetype: "cowboy", weight: 1.0 },
+  "warn-all-files-staged":     { archetype: "cowboy", weight: 0.6 },
+  "block-kubectl":             { archetype: "cowboy", weight: 1.5 },
+  "block-terraform":           { archetype: "cowboy", weight: 1.5 },
+  "block-helm":                { archetype: "cowboy", weight: 1.2 },
+  "block-aws-cli":             { archetype: "cowboy", weight: 1.2 },
+  "block-gcloud":              { archetype: "cowboy", weight: 1.2 },
+  "block-az-cli":              { archetype: "cowboy", weight: 1.2 },
+  "block-gh-pipeline":         { archetype: "cowboy", weight: 1.2 },
+
+  // ── explorer ── boundary crossing / secrets exposure (9) ──────────────────
+  // NOTE: `block-read-outside-cwd` is deliberately NOT mapped to a persona. It
+  // is `defaultEnabled: false` (so real users don't even enforce it) and fires
+  // on any absolute-path read outside cwd — ambient, volume-scaled behaviour
+  // present in essentially every session, not an elective "explorer" tendency.
+  // Replay force-registers it regardless of config, so leaving it here made it
+  // the single largest signal (≈37% of all mapped signal in real audits) and
+  // collapsed the whole population onto "the explorer". It still appears in the
+  // audit report; it just no longer drives the archetype.
+  "sanitize-private-key-content":{ archetype: "explorer", weight: 1.5 },
+  "block-env-files":           { archetype: "explorer", weight: 1.5 },
+  "block-secrets-write":       { archetype: "explorer", weight: 1.5 },
+  "sanitize-api-keys":         { archetype: "explorer", weight: 1.2 },
+  "sanitize-jwt":              { archetype: "explorer", weight: 1.2 },
+  "sanitize-connection-strings":{ archetype: "explorer", weight: 1.2 },
+  "sanitize-bearer-tokens":    { archetype: "explorer", weight: 1.0 },
+  "protect-env-vars":          { archetype: "explorer", weight: 1.0 },
+  "find-from-root":            { archetype: "explorer", weight: 1.0 },
+
+  // ── ghost ── unfinished / unsupervised work (7) ───────────────────────────
+  // NOTE: the five require-*-before-stop policies only fire on `Stop` events,
+  // which the audit replay never synthesises, so in practice ghost is reached
+  // via warn-large-file-write + warn-background-process. They are mapped here
+  // for completeness and in case a future Stop-replay path is added.
+  "require-ci-green-before-stop":   { archetype: "ghost", weight: 1.2 },
+  "require-commit-before-stop":     { archetype: "ghost", weight: 1.2 },
+  "require-push-before-stop":       { archetype: "ghost", weight: 1.0 },
+  "require-pr-before-stop":         { archetype: "ghost", weight: 1.0 },
+  "require-no-conflicts-before-stop":{ archetype: "ghost", weight: 1.0 },
+  "warn-large-file-write":     { archetype: "ghost", weight: 1.0 },
+  "warn-background-process":   { archetype: "ghost", weight: 0.8 },
+
+  // ── optimist ── low-friction shortcuts / sloppy tool choice (6) ───────────
+  "warn-package-publish":      { archetype: "optimist", weight: 1.0 },
+  "warn-global-package-install":{ archetype: "optimist", weight: 0.8 },
+  "prefer-package-manager":    { archetype: "optimist", weight: 0.8 },
+  "prefer-edit-over-sed-awk":  { archetype: "optimist", weight: 0.8 },
+  "prefer-edit-over-read-cat": { archetype: "optimist", weight: 0.5 },
+  "prefer-write-over-heredoc": { archetype: "optimist", weight: 0.5 },
+
+  // ── hammer ── brute-force repetition (2) ──────────────────────────────────
+  "warn-repeated-tool-calls":  { archetype: "hammer", weight: 1.5 },
+  "sleep-polling-loop":        { archetype: "hammer", weight: 1.2 },
+
+  // ── architect ── over-verification "caution" signals (2) ──────────────────
+  "reread-after-edit":         { archetype: "architect", weight: 1.0 },
+  "redundant-cd-cwd":          { archetype: "architect", weight: 0.8 },
+};
+
+/** Builtin severity derived from the policy name prefix. The builtin
+ *  definitions carry no static severity field — the runtime decision lives in
+ *  the policy fn — but the name prefix encodes intent deterministically:
+ *    sanitize-* → sanitize (gentle)   warn-/protect-/prefer-/require-* → warn
+ *    block-*    → deny (severe)        anything else → deny (safe default)
+ *  Replaces the old hardcoded `"deny"` so the score's medium/gentle buckets
+ *  actually populate. */
+export function severityForBuiltin(name: string): string {
+  const n = shortName(name);
+  if (n.startsWith("sanitize-")) return "sanitize";
+  if (n.startsWith("block-")) return "deny";
+  if (
+    n.startsWith("warn-") || n.startsWith("protect-") ||
+    n.startsWith("prefer-") || n.startsWith("require-")
+  ) return "warn";
+  return "deny";
+}
+
+function emptyWeights(): Record<ArchetypeKey, number> {
+  return {
+    optimist: 0, cowboy: 0, explorer: 0, goldfish: 0,
+    architect: 0, precision: 0, hammer: 0, ghost: 0,
+  };
+}
+
+/** A rare-but-elective cluster floor for the lift denominator. Without it a
+ *  cluster that barely fires under replay (e.g. ghost) would have a near-zero
+ *  baseline and explode to a huge lift off a single hit, hijacking the persona
+ *  from one stray signal. 0.05 ≈ "you need a few % of your signal here to count
+ *  as over-indexing", which is the right bar for the long tail. */
+const MIN_BASELINE = 0.05;
+
+/**
+ * EMPIRICAL firing share of each mappable cluster for a *typical* agent —
+ * measured from a corpus of real audits, NOT derived from catalog weights.
+ *
+ * The original implementation set the baseline to each persona's share of the
+ * `SIGNAL_MAP` *catalog* (Σ its weights ÷ Σ all weights), on the theory that
+ * lift would then cancel cowboy's 20-signal surface area. But catalog share ≠
+ * real firing rate. The ambient policies feeding `explorer` (env access,
+ * secrets-in-tool-output) and `architect` (reread-after-edit, redundant-cd)
+ * fire on benign, volume-scaled activity in nearly every session — far above
+ * their catalog share — while cowboy's destructive `block-*` policies almost
+ * never fire. A catalog baseline therefore kept explorer's lift > 1 for almost
+ * every real user and collapsed the entire population onto a single persona.
+ * Calibrating the denominator to real firing frequency is what removes that
+ * systemic skew: a cluster now wins only when it fires *more than typical*.
+ *
+ * These need only track the *relative* ambient firing frequency of each
+ * cluster; they don't have to sum to 1. Refine as the corpus grows.
+ */
+export const EMPIRICAL_FIRING_SHARE: Record<ArchetypeKey, number> = {
+  explorer: 0.38,
+  architect: 0.33,
+  hammer: 0.11,
+  cowboy: 0.11,
+  optimist: 0.07,
+  ghost: 0.01,
+  precision: 0,
+  goldfish: 0,
+};
+
+/** Lift denominator: observed-share ÷ baseline-share. Empirically calibrated
+ *  (see EMPIRICAL_FIRING_SHARE) and floored at MIN_BASELINE for the long tail. */
+export const BASELINE_SHARE: Record<ArchetypeKey, number> = (() => {
+  const out = emptyWeights();
+  for (const k of MAPPABLE_KEYS) out[k] = Math.max(EMPIRICAL_FIRING_SHARE[k], MIN_BASELINE);
+  return out;
+})();
+
+/** Normalised Shannon entropy of a lift vector, base = number of mappable
+ *  clusters (6). 0 = all signal in one persona, 1 = perfectly even spread.
+ *  Two equally-lit clusters score ~0.39 (not goldfish); ~4 even clusters
+ *  cross 0.77 (goldfish territory). */
+function normalizedEntropy(vals: number[]): number {
+  const total = vals.reduce((s, v) => s + Math.max(0, v), 0);
+  if (total <= 0) return 0;
+  let h = 0;
+  for (const v of vals) {
+    if (v <= 0) continue;
+    const p = v / total;
+    h -= p * Math.log(p);
+  }
+  return h / Math.log(vals.length);
+}
+
+/** Volume floor — a 3-call session shouldn't divide-by-tiny and explode. */
+export const MIN_EVENTS = 50;
+
+export interface AuditFeatures {
+  /** Tool calls scanned, floored at MIN_EVENTS. */
+  events: number;
+  sessions: number;
+  totalHits: number;
+  /** totalHits / events — the cleanliness denominator the old scorer ignored. */
+  faultRate: number;
+  /** Per-persona Σ(hits × weight). Same shape the old classifier returned. */
+  clusterRaw: Record<ArchetypeKey, number>;
+  totalSignal: number;
+  /** Per-persona observed-share ÷ baseline-share. The ranking metric. */
+  clusterLift: Record<ArchetypeKey, number>;
+  /** Normalised entropy of the lift vector (goldfish detector). */
+  entropy: number;
+  /** Second-highest cluster lift. Goldfish requires this to be elevated:
+   *  high entropy alone is satisfied by a uniform-at-baseline lift vector
+   *  (every cluster fires at ambient rate → lifts ≈ 1.0 → entropy = max),
+   *  which would otherwise collapse every "typical" agent onto goldfish. */
+  secondLift: number;
+  /** Share of total signal coming from the two architect caution detectors. */
+  cautionShare: number;
+  cowboyLift: number;
+  /** Deterministic hash of the rounded behaviour vector + seed. Seeds
+   *  tie-breaks and copy-variant selection. */
+  fingerprint: number;
+}
+
+function sumHits(result: AuditResult): number {
+  let s = 0;
+  for (const r of result.results) s += r.hits;
+  return s;
+}
+
+/** Derive the behaviour feature vector. Pure over (result, seed). */
+export function deriveFeatures(result: AuditResult, seed = ""): AuditFeatures {
+  const events = Math.max(result.eventsScanned ?? 0, MIN_EVENTS);
+  const sessions = result.transcripts.scanned;
+  const totalHits = result.totals?.hits ?? sumHits(result);
+
+  const clusterRaw = emptyWeights();
+  let cautionRaw = 0;
+  for (const row of result.results) {
+    const short = shortName(row.name);
+    const sig = SIGNAL_MAP[short];
+    if (!sig) continue;
+    const w = row.hits * sig.weight;
+    clusterRaw[sig.archetype] += w;
+    if (ARCHITECT_CAUTION_SIGNALS.has(short)) cautionRaw += w;
+  }
+
+  const totalSignal = MAPPABLE_KEYS.reduce((s, k) => s + clusterRaw[k], 0);
+
+  const clusterLift = emptyWeights();
+  for (const k of MAPPABLE_KEYS) {
+    const share = totalSignal > 0 ? clusterRaw[k] / totalSignal : 0;
+    clusterLift[k] = BASELINE_SHARE[k] > 0 ? share / BASELINE_SHARE[k] : 0;
+  }
+
+  const liftVec = MAPPABLE_KEYS.map((k) => clusterLift[k]);
+  const entropy = normalizedEntropy(liftVec);
+  const sortedLifts = [...liftVec].sort((a, b) => b - a);
+  const secondLift = sortedLifts[1] ?? 0;
+  const cautionShare = totalSignal > 0 ? cautionRaw / totalSignal : 0;
+  const faultRate = totalHits / events;
+
+  // Fingerprint: stable over the rounded behaviour signature + seed. Rounding
+  // keeps it stable against floating-point noise while still varying between
+  // genuinely different agents.
+  const sig = MAPPABLE_KEYS.map((k) => Math.round(clusterRaw[k] * 10)).join(",");
+  const fingerprint = hashSeed(`${seed}|${sig}|${Math.round(faultRate * 1000)}`);
+
+  return {
+    events, sessions, totalHits, faultRate,
+    clusterRaw, totalSignal, clusterLift, entropy, secondLift,
+    cautionShare, cowboyLift: clusterLift.cowboy, fingerprint,
+  };
+}