@drewpayment/mink 0.13.0-beta.1 → 0.13.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drewpayment/mink",
-  "version": "0.13.0-beta.1",
+  "version": "0.13.0-beta.3",
   "description": "A hidden presence that moves alongside the developer — token efficiency and cross-project wiki for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -16,24 +16,8 @@ switch (command) {
     break;
 
   case "init": {
-    const { init, resolveTargetsFromFlag } = await import("./commands/init");
-    const args = process.argv.slice(3);
-    const agentFlagIndex = args.findIndex(
-      (a) => a === "--agent" || a.startsWith("--agent=")
-    );
-    let agentValue: string | undefined;
-    if (agentFlagIndex !== -1) {
-      const a = args[agentFlagIndex];
-      agentValue = a.includes("=") ? a.split("=").slice(1).join("=") : args[agentFlagIndex + 1];
-    }
-    const yes = args.includes("--yes") || args.includes("-y");
-    const targets = agentValue ? resolveTargetsFromFlag(agentValue) : undefined;
-    if (agentValue && (!targets || targets.length === 0)) {
-      console.error(`[mink] unknown --agent value: ${agentValue}`);
-      console.error("  Valid: claude, pi, all (or a comma-separated list)");
-      process.exit(1);
-    }
-    await init(cwd, { targets, interactive: !yes });
+    const { init } = await import("./commands/init");
+    await init(cwd);
     break;
   }
 
@@ -69,6 +53,12 @@ switch (command) {
     break;
   }
 
+  case "post-tool": {
+    const { postTool } = await import("./commands/post-tool");
+    await postTool(cwd);
+    break;
+  }
+
   case "pre-write": {
     const { preWrite } = await import("./commands/pre-write");
     await preWrite(cwd);
@@ -87,6 +77,12 @@ switch (command) {
     break;
   }
 
+  case "retrieve": {
+    const { retrieve } = await import("./commands/retrieve");
+    retrieve(cwd, process.argv.slice(3));
+    break;
+  }
+
   case "cron": {
     const { cron } = await import("./commands/cron");
     await cron(cwd, process.argv.slice(3));
@@ -237,8 +233,7 @@ switch (command) {
     console.log("Usage: mink <command> [options]");
     console.log();
     console.log("Commands:");
-    console.log("  init [--agent X] [--yes] Initialize Mink in the current project");
-    console.log("                          --agent claude|pi|all (default: detect & prompt)");
+    console.log("  init                    Initialize Mink in the current project");
     console.log("  status                  Display project health at a glance");
     console.log("  scan [--check]          Force a full file index rescan");
     console.log("  config [key] [value]    Manage global user settings");
@@ -280,6 +275,7 @@ switch (command) {
     console.log("  restore [backup]        Restore state from a backup");
     console.log("  bug search <term>       Search the bug log");
     console.log("  detect-waste            Detect and flag wasteful patterns");
+    console.log("  retrieve <token>        Return a compressed tool output's original (spec 21)");
     console.log("  reflect                 Generate learning memory reflections");
     console.log("  designqc [target]       Capture design screenshots (spec 13)");
     console.log("  framework-advisor       Generate framework advisor knowledge file (spec 14)");
@@ -289,6 +285,7 @@ switch (command) {
     console.log("  session-stop            Finalize session and log data");
     console.log("  pre-read / post-read    File read hooks");
     console.log("  pre-write / post-write  File write hooks");
+    console.log("  post-tool               Tool-output compression hook (Bash/Grep/MCP, spec 21)");
     break;
 
   default:

package/src/commands/init.ts

@@ -12,23 +12,6 @@ import {
   isInsideVault,
   vaultProjects,
 } from "../core/vault";
-import {
-  type AgentId,
-  AGENTS,
-  detectAgents,
-  resolveTargetsFromFlag,
-} from "../core/agent-detect";
-import { installPi } from "../core/agent-pi";
-import { ask, stdinIsInteractive } from "../core/prompt";
-
-export { resolveTargetsFromFlag };
-
-export interface InitOptions {
-  /** Explicit set of hosts to wire. When omitted, Mink detects and/or prompts. */
-  targets?: AgentId[];
-  /** Allow an interactive agent-selection prompt when stdin is a TTY. */
-  interactive?: boolean;
-}
 
 interface HookCommand {
   type: "command";
@@ -108,6 +91,9 @@ export function buildHooksConfig(cliPath: string): HooksConfig {
       { matcher: "Read", hooks: hook(`${prefix} post-read`) },
       { matcher: "Edit", hooks: hook(`${prefix} post-write`) },
       { matcher: "Write", hooks: hook(`${prefix} post-write`) },
+      // Tool-output compression (spec 21) — a no-op until enabled via config.
+      { matcher: "Bash", hooks: hook(`${prefix} post-tool`) },
+      { matcher: "Grep", hooks: hook(`${prefix} post-tool`) },
     ],
   };
 }
@@ -119,7 +105,8 @@ function isMinkCommand(cmd: string): boolean {
     cmd.includes("pre-read") ||
     cmd.includes("post-read") ||
     cmd.includes("pre-write") ||
-    cmd.includes("post-write");
+    cmd.includes("post-write") ||
+    cmd.includes("post-tool");
   if (!hasMinkSubcommand) return false;
   // Match the new bin-shim format (`mink <subcmd>` or `/abs/path/to/mink <subcmd>`)
   // as well as legacy formats (`bun run .../cli.js ...`, `node .../cli.js ...`,
@@ -185,80 +172,17 @@ export function mergeHooksIntoSettings(
   atomicWriteJson(settingsPath, existing);
 }
 
-/** Wire Mink into Claude Code: settings.json hooks + the project rule file. */
-export function installClaude(
-  cwd: string,
-  cliPath: string
-): { settingsPath: string; rulePath: string } {
-  const settingsPath = resolve(cwd, ".claude", "settings.json");
-  mergeHooksIntoSettings(settingsPath, buildHooksConfig(cliPath));
-  const rulePath = writeMinkRule(cwd);
-  return { settingsPath, rulePath };
-}
-
-/**
- * Decide which hosts to wire. Explicit `targets` win; otherwise Mink detects
- * installed hosts and — only when running interactively at a TTY — asks the
- * user to confirm. Non-interactive runs fall back to the detected set, and to
- * Claude Code when nothing is detected (preserving Mink's original behavior).
- */
-export async function resolveTargets(
-  cwd: string,
-  opts: InitOptions
-): Promise<AgentId[]> {
-  if (opts.targets && opts.targets.length > 0) return opts.targets;
-
-  const detected = detectAgents(cwd);
-  const detectedIds = detected.filter((a) => a.detected).map((a) => a.id);
-
-  if (opts.interactive && stdinIsInteractive()) {
-    return promptForAgents(detected, detectedIds);
-  }
-
-  return detectedIds.length > 0 ? detectedIds : ["claude"];
-}
-
-async function promptForAgents(
-  detected: ReturnType<typeof detectAgents>,
-  defaults: AgentId[]
-): Promise<AgentId[]> {
-  const fallback: AgentId[] = defaults.length > 0 ? defaults : ["claude"];
-
-  console.log("Which assistant(s) should Mink work with?");
-  detected.forEach((a, i) => {
-    const tag = a.detected ? `  (detected — ${a.signals.join(", ")})` : "";
-    console.log(`  ${i + 1}) ${a.label}${tag}`);
-  });
-
-  const answer = (
-    await ask(
-      `Enter numbers (comma-separated), 'a' for all [default: ${fallback.join(", ")}]: `
-    )
-  )
-    .trim()
-    .toLowerCase();
-
-  if (answer === "") return fallback;
-  if (answer === "a" || answer === "all") return AGENTS.map((a) => a.id);
-
-  const picked = answer
-    .split(",")
-    .map((s) => parseInt(s.trim(), 10))
-    .filter((n) => Number.isInteger(n) && n >= 1 && n <= detected.length)
-    .map((n) => detected[n - 1].id);
-
-  return picked.length > 0 ? picked : fallback;
-}
-
 function isExistingInstallation(cwd: string): boolean {
   const dir = projectDir(cwd);
   if (!existsSync(dir)) return false;
   return existsSync(join(dir, "file-index.json"));
 }
 
-export async function init(cwd: string, opts: InitOptions = {}): Promise<void> {
+export async function init(cwd: string): Promise<void> {
   const runtime = detectRuntime();
   const cliPath = resolveCliPath();
+  const hooks = buildHooksConfig(cliPath);
+  const settingsPath = resolve(cwd, ".claude", "settings.json");
   const dir = projectDir(cwd);
   const upgrading = isExistingInstallation(cwd);
 
@@ -269,25 +193,8 @@ export async function init(cwd: string, opts: InitOptions = {}): Promise<void> {
     console.log(`  backup: ${backupName}`);
   }
 
-  const targets = await resolveTargets(cwd, opts);
-
-  // Wire each selected host. Each installer is idempotent — re-running replaces
-  // Mink's prior entries rather than duplicating them — and touches only that
-  // host's configuration.
-  const wired: Record<string, string[]> = {};
-  for (const target of targets) {
-    if (target === "claude") {
-      const { settingsPath, rulePath } = installClaude(cwd, cliPath);
-      wired.claude = [`hooks: ${settingsPath}`, `rule:  ${rulePath}`];
-    } else if (target === "pi") {
-      const r = installPi(cwd, cliPath);
-      wired.pi = [
-        `extension: ${r.extensionPath}`,
-        `guidance:  ${r.guidancePath}`,
-        ...(r.notePath ? [`note skill: ${r.notePath}`] : []),
-      ];
-    }
-  }
+  mergeHooksIntoSettings(settingsPath, hooks);
+  const rulePath = writeMinkRule(cwd);
 
   mkdirSync(dir, { recursive: true });
 
@@ -310,13 +217,6 @@ export async function init(cwd: string, opts: InitOptions = {}): Promise<void> {
     !Array.isArray(existingMeta.pathsByDevice)
       ? (existingMeta.pathsByDevice as Record<string, string>)
       : {};
-  // Record the set of wired hosts as the authoritative source of truth, unioned
-  // with any previously wired host so a single-target re-init never silently
-  // unwires the other.
-  const priorAgents = Array.isArray(existingMeta?.agents)
-    ? (existingMeta!.agents as string[])
-    : [];
-  const agents = Array.from(new Set([...priorAgents, ...targets]));
   atomicWriteJson(metaPath, {
     ...(existingMeta ?? {}),
     cwd,
@@ -324,30 +224,21 @@ export async function init(cwd: string, opts: InitOptions = {}): Promise<void> {
     initTimestamp: existingMeta?.initTimestamp ?? new Date().toISOString(),
     version: "0.1.0",
     pathsByDevice: { ...existingPathsByDevice, [deviceId]: cwd },
-    agents,
     ...(isNotesProject ? { projectType: "notes" } : {}),
   });
 
-  const printWiring = () => {
-    for (const id of Object.keys(wired)) {
-      const label = AGENTS.find((a) => a.id === id)?.label ?? id;
-      console.log(`  ${label}:`);
-      for (const line of wired[id]) console.log(`    ${line}`);
-    }
-  };
-
   if (upgrading) {
     console.log(`[mink] upgrade complete`);
     console.log(`  project:  ${projectId}`);
-    console.log(`  agents:   ${agents.join(", ")}`);
-    printWiring();
+    console.log(`  hooks:    ${settingsPath}`);
+    console.log(`  rule:     ${rulePath}`);
   } else {
     console.log(`[mink] initialized`);
     console.log(`  project:  ${projectId} (${identity.source})`);
     console.log(`  state:    ${dir}`);
     console.log(`  runtime:  ${runtime}`);
-    console.log(`  agents:   ${agents.join(", ")}`);
-    printWiring();
+    console.log(`  hooks:    ${settingsPath}`);
+    console.log(`  rule:     ${rulePath}`);
   }
 
   // Surface a one-time hint when the project is in a git repo with no remote

package/src/commands/post-read.ts

@@ -9,6 +9,8 @@ import { estimateTokens, isBinaryFile } from "../core/token-estimate";
 import { extractDescription } from "../core/description";
 import { createActionLogWriter } from "../core/action-log";
 import { getOrCreateDeviceId } from "../core/device";
+import { compressToolOutput } from "../core/compress-tool-output";
+import { emitUpdatedToolOutput } from "../core/hook-output";
 import type { SessionState } from "../types/session";
 import type { FileIndexEntry, IndexLookup } from "../types/file-index";
 import type { PostToolUseInput } from "../types/hook-input";
@@ -202,6 +204,22 @@ export async function postRead(cwd: string): Promise<void> {
 
     // Persist state
     atomicWriteJson(sessionPath(cwd), state);
+
+    // Tool-output compression (spec 21). Substitute a compact, reversible
+    // summary for a large whole-file read. Skipped for ranged reads (their
+    // output is only a slice) and a no-op unless compression is enabled. Uses
+    // the on-disk content as the canonical original so signature extraction
+    // works on raw source and `mink retrieve` returns the file itself.
+    const isRanged =
+      input.tool_input.offset != null || input.tool_input.limit != null;
+    if (!isRanged && content && content.length > 0) {
+      try {
+        const outcome = compressToolOutput(cwd, "Read", content, filePath);
+        if (outcome) emitUpdatedToolOutput(outcome.updatedToolOutput);
+      } catch {
+        // Compression is advisory — never break the read over it.
+      }
+    }
   } catch {
     // Never crash — exit silently
   } finally {

package/src/commands/post-tool.ts

@@ -0,0 +1,48 @@
+// Generic PostToolUse compression hook (spec 21) for tools that produce large,
+// non-file output — Bash, Grep/Glob, and MCP tools. The Read tool is handled by
+// post-read (which has the on-disk content and ranged-read awareness); this hook
+// compresses the payload text directly.
+//
+// Like every Mink hook: non-blocking, time-boxed, and silent on failure. It is a
+// no-op unless compression is enabled, so wiring it up costs nothing until the
+// user opts in.
+
+import { readStdinJson } from "../core/stdin";
+import { extractToolOutputText, emitUpdatedToolOutput } from "../core/hook-output";
+import { compressToolOutput } from "../core/compress-tool-output";
+import type { PostToolUseInput } from "../types/hook-input";
+
+function isPostToolUseInput(value: unknown): value is PostToolUseInput {
+  if (value === null || typeof value !== "object") return false;
+  const obj = value as Record<string, unknown>;
+  return typeof obj.tool_name === "string";
+}
+
+// Tools whose output we compress here. Read is excluded (post-read owns it).
+function isCompressibleTool(toolName: string): boolean {
+  return (
+    toolName === "Bash" ||
+    toolName === "Grep" ||
+    toolName === "Glob" ||
+    toolName.startsWith("mcp__")
+  );
+}
+
+export async function postTool(cwd: string): Promise<void> {
+  const timer = setTimeout(() => process.exit(0), 5000);
+  try {
+    const input = await readStdinJson();
+    if (!isPostToolUseInput(input)) return;
+    if (!isCompressibleTool(input.tool_name)) return;
+
+    const output = extractToolOutputText(input);
+    if (!output) return;
+
+    const outcome = compressToolOutput(cwd, input.tool_name, output);
+    if (outcome) emitUpdatedToolOutput(outcome.updatedToolOutput);
+  } catch {
+    // Never crash — exit silently.
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/commands/retrieve.ts

@@ -0,0 +1,32 @@
+// `mink retrieve <token>` — return the byte-exact original of a previously
+// compressed tool output (spec 21 §Reversibility). Prints the original to
+// stdout on a hit; on a miss (unknown or expired token) it prints a short,
+// non-fatal notice to stderr and exits 0 so the assistant is never stranded by
+// an error.
+
+import { CompressionCacheRepo } from "../repositories/compression-cache-repo";
+
+export function retrieve(cwd: string, args: string[]): void {
+  const token = args[0];
+  if (!token) {
+    process.stderr.write("[mink] usage: mink retrieve <token>\n");
+    return;
+  }
+
+  let entry = null;
+  try {
+    entry = CompressionCacheRepo.for(cwd).get(token);
+  } catch {
+    // Treat any storage error as a miss — never throw at the assistant.
+    entry = null;
+  }
+
+  if (!entry) {
+    process.stderr.write(
+      `[mink] no retrievable output for token "${token}" (unknown or expired)\n`
+    );
+    return;
+  }
+
+  process.stdout.write(entry.content);
+}

package/src/commands/status.ts

@@ -149,7 +149,19 @@ export function status(cwd: string): void {
     console.log(`    Sessions: ${lt.totalSessions}`);
     console.log(`    Total tokens: ${lt.totalTokens.toLocaleString()}`);
     console.log(`    Reads: ${lt.totalReads}  Writes: ${lt.totalWrites}`);
-    console.log(`    Estimated savings: ${lt.totalEstimatedSavings.toLocaleString()} tokens`);
+    console.log(`    Estimated savings (heuristic): ${lt.totalEstimatedSavings.toLocaleString()} tokens`);
+    const comp = ledger.compression;
+    if (comp && comp.totalEvents > 0) {
+      const ratio =
+        comp.totalOriginalTokens > 0
+          ? Math.round((comp.totalMeasuredSavings / comp.totalOriginalTokens) * 100)
+          : 0;
+      console.log(
+        `    Measured compression savings: ${comp.totalMeasuredSavings.toLocaleString()} tokens` +
+          ` (${ratio}% over ${comp.totalEvents} event${comp.totalEvents === 1 ? "" : "s"}` +
+          `, ${comp.totalHoldoutEvents} held out)`
+      );
+    }
   } catch {
     console.log("  Token ledger: error reading");
   }

package/src/core/code-skeleton.ts

@@ -0,0 +1,108 @@
+// Deterministic, dependency-free code skeleton extraction (spec 21 phase 3).
+//
+// Produces a structural outline of source: top-level declarations and the direct
+// members of classes/interfaces, with function/method bodies elided to "{ … }".
+// It is brace-depth aware (with strings and comments masked so stray braces don't
+// desync the depth), which lets it descend into a class to capture method
+// signatures while suppressing the statements inside those methods.
+//
+// This is a heuristic skeleton, not a real parser — Mink stays zero-dependency.
+// Because tool-output compression is reversible (the original is cached), a
+// slightly imperfect skeleton is harmless: the model can always `mink retrieve`.
+// The same extractor is intended to enrich the file index later.
+
+const MAX_SIGNATURES = 80;
+const INDENT = "  ";
+
+// Declarations that always anchor the skeleton.
+const DECL_ALWAYS =
+  /^\s*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?(?:async\s+)?(?:function|class|interface|type|enum|namespace|module|def|fn|func|impl|struct|trait)\b/;
+// Variable declarations only matter to the public surface when exported.
+const DECL_EXPORTED_VAR = /^\s*export\s+(?:default\s+)?(?:const|let|var)\b/;
+// Inside a class/interface body (depth >= 1): method signatures and fields.
+const MEMBER =
+  /^\s*(?:public\s+|private\s+|protected\s+|readonly\s+|static\s+|async\s+|get\s+|set\s+|#)*[\w$]+\??\s*(?:\(|:|=)/;
+// Markdown headings (only honoured for markdown files).
+const HEADING = /^#{1,6}\s+\S/;
+// Keywords whose block we descend into to capture members rather than elide.
+const DESCEND = /\b(?:class|interface|enum|namespace|module|struct|trait|impl)\b/;
+
+function countChar(s: string, c: string): number {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) if (s[i] === c) n++;
+  return n;
+}
+
+// Net brace delta for a line, with strings and comments masked so braces inside
+// them don't affect depth tracking.
+function netBraces(line: string): number {
+  let s = line.replace(/\/\/.*$/, "");
+  s = s.replace(/\/\*.*?\*\//g, "");
+  s = s.replace(/"(?:\\.|[^"\\])*"/g, '""');
+  s = s.replace(/'(?:\\.|[^'\\])*'/g, "''");
+  s = s.replace(/`(?:\\.|[^`\\])*`/g, "``");
+  return countChar(s, "{") - countChar(s, "}");
+}
+
+function stripOpenBrace(sig: string): string {
+  return sig.replace(/\{\s*$/, "").trimEnd();
+}
+
+export interface CodeSkeleton {
+  lines: string[];
+  totalLines: number;
+}
+
+// Extract a skeleton, or null when the content has no recognisable structure
+// (the caller then falls back to a generic text window).
+export function extractCodeSkeleton(
+  content: string,
+  opts: { markdown?: boolean } = {}
+): CodeSkeleton | null {
+  const rawLines = content.split("\n");
+  const totalLines =
+    rawLines.length > 0 && rawLines[rawLines.length - 1] === ""
+      ? rawLines.length - 1
+      : rawLines.length;
+
+  const out: string[] = [];
+  let depth = 0;
+  let suppress = Infinity; // suppress lines while inside an elided function body
+
+  for (const line of rawLines) {
+    if (out.length >= MAX_SIGNATURES) break;
+    const start = depth;
+    const net = netBraces(line);
+
+    if (start < suppress) {
+      const isHeading = opts.markdown === true && HEADING.test(line);
+      const captured =
+        isHeading ||
+        DECL_ALWAYS.test(line) ||
+        DECL_EXPORTED_VAR.test(line) ||
+        (start >= 1 && MEMBER.test(line));
+
+      if (captured) {
+        // Trim the source indentation; we re-indent by structural depth.
+        const sig = line.trim();
+        if (net > 0) {
+          if (DESCEND.test(line) && !isHeading) {
+            out.push(INDENT.repeat(start) + stripOpenBrace(sig) + " {");
+            // descend — keep capturing members at the next depth
+          } else {
+            out.push(INDENT.repeat(start) + stripOpenBrace(sig) + " { … }");
+            suppress = start + 1; // skip this body's contents
+          }
+        } else {
+          out.push(INDENT.repeat(start) + sig);
+        }
+      }
+    }
+
+    depth = Math.max(0, depth + net);
+    if (depth < suppress) suppress = Infinity; // left the elided body
+  }
+
+  if (out.length === 0) return null;
+  return { lines: out, totalLines };
+}

package/src/core/compress-tool-output.ts

@@ -0,0 +1,127 @@
+// Compression pipeline orchestrator (spec 21). Ties together the config/holdout
+// decisions, the pure engine, the reversible cache, and the ledger. Returns the
+// replacement text to emit, or null to pass the original through unchanged.
+//
+// Invariants:
+// - Disabled by default (config gate) → no-op.
+// - Reversible or nothing: the original is stored BEFORE we return a compressed
+//   result; if storage fails we pass the original through, so a compressed
+//   result is never shown without a retrievable original (spec 21 edge case).
+// - Every failure degrades to "no compression" — a hook must never throw.
+// - Holdout arms pass the original through but are still measured.
+
+import {
+  loadCompressionConfig,
+  isEligible,
+  meetsMinSavings,
+  selectHoldout,
+} from "./compression";
+import { countTokens } from "./token-estimate";
+import { compressOutput, detectContentKind } from "./output-compression";
+import type { CompressionResult } from "../types/compression";
+import { CompressionCacheRepo } from "../repositories/compression-cache-repo";
+import { TokenLedgerRepo } from "../repositories/token-ledger-repo";
+
+// Deterministic FNV-1a → hex, used as a stable per-event key so an identical
+// output always lands in the same holdout arm (spec 21 edge case).
+function contentKey(s: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16);
+}
+
+// Render the replacement: stable compressed body first, volatile retrieval
+// footer (random token) last — matching Mink's "volatile at the end" cache
+// discipline so the body forms a stable prefix.
+function render(result: CompressionResult, token: string): string {
+  return (
+    result.compressed +
+    "\n\n" +
+    `— mink: compressed ${result.kind} output (${result.omittedNote}). ` +
+    `Full original: mink retrieve ${token}`
+  );
+}
+
+function safeRecord(
+  cwd: string,
+  toolName: string,
+  contentKind: string,
+  originalTokens: number,
+  compressedTokens: number,
+  holdout: boolean
+): void {
+  try {
+    TokenLedgerRepo.for(cwd).recordCompression({
+      toolName,
+      contentKind,
+      originalTokens,
+      compressedTokens,
+      holdout,
+    });
+  } catch {
+    // Measurement is best-effort — never block the hook over a ledger write.
+  }
+}
+
+export interface CompressOutcome {
+  updatedToolOutput: string;
+  token: string;
+}
+
+export function compressToolOutput(
+  cwd: string,
+  toolName: string,
+  output: string,
+  filePath?: string
+): CompressOutcome | null {
+  let cfg;
+  try {
+    cfg = loadCompressionConfig();
+  } catch {
+    return null;
+  }
+  if (!cfg.enabled) return null;
+  if (typeof output !== "string" || output.length === 0) return null;
+
+  const originalTokens = countTokens(output);
+  if (!isEligible(originalTokens, cfg)) return null;
+
+  const eventKey = contentKey(output);
+
+  // Holdout arm: pass the original through, but record it as a control.
+  if (selectHoldout(eventKey, cfg.holdoutFraction)) {
+    const kind = detectContentKind(toolName, output, filePath);
+    safeRecord(cwd, toolName, kind, originalTokens, originalTokens, true);
+    return null;
+  }
+
+  const result = compressOutput(toolName, output, filePath);
+  if (!result) return null;
+
+  const token = CompressionCacheRepo.newToken();
+  const replacement = render(result, token);
+  const compressedTokens = countTokens(replacement);
+
+  // Discard a weak compression and pass the original through.
+  if (!meetsMinSavings(originalTokens, compressedTokens, cfg)) return null;
+
+  // Store the original FIRST. If we cannot, do not compress — never show a
+  // compressed result without a retrievable original.
+  try {
+    CompressionCacheRepo.for(cwd).store({
+      toolName,
+      contentKind: result.kind,
+      content: output,
+      retentionHours: cfg.retentionHours,
+      token,
+    });
+  } catch {
+    return null;
+  }
+
+  safeRecord(cwd, toolName, result.kind, originalTokens, compressedTokens, false);
+  return { updatedToolOutput: replacement, token };
+}