greprag 5.41.0 → 5.42.1

package/dist/commands/context-governor.js

@@ -0,0 +1,344 @@
+"use strict";
+/** Context governor — tracks the session's live context size every turn and,
+ *  past a configurable crossover threshold (default 400K tokens), injects a
+ *  one-line advisory recommending a governed compact.
+ *
+ *  Why 400K: per-turn cache-read overhead is linear in context size N and
+ *  overtakes the productive cost of a turn at roughly N ≈ 400-425K tokens.
+ *  Past that, most of each turn's cost is re-reading frozen history — the
+ *  economically right moment to compact, BEFORE the window forces it.
+ *  See docs/pre-llm-compression.md (§ cache cost model).
+ *
+ *  Three surfaces, all local (no API, no LLM):
+ *    - Stop probe (`greprag-hook context-probe`): read the transcript TAIL
+ *      (last ~64KB, never the whole multi-MB file), compute context size from
+ *      the most recent main-chain assistant entry's `message.usage`, write
+ *      ~/.greprag/context-state/<8hex>.json.
+ *    - UserPromptSubmit check (`greprag-hook context-check`): state over
+ *      threshold → emit ONE advisory line, at most once per 25-turn window.
+ *    - CLI (`greprag context status`): debugging/demo readout.
+ *
+ *  Config follows the anchor-settings pattern (email_autosave precedent):
+ *  `.greprag/project.json` keys `context_governor` (bool) + `context_threshold`
+ *  (number), env overrides GREPRAG_CONTEXT_GOVERNOR / GREPRAG_CONTEXT_THRESHOLD.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAIL_BYTES = exports.FIRE_WINDOW_TURNS = exports.DEFAULT_CONTEXT_THRESHOLD = void 0;
+exports.computeContextSizeFromTail = computeContextSizeFromTail;
+exports.readTranscriptTail = readTranscriptTail;
+exports.contextStateDir = contextStateDir;
+exports.contextStatePath = contextStatePath;
+exports.readGovernorState = readGovernorState;
+exports.writeGovernorState = writeGovernorState;
+exports.readGovernorConfig = readGovernorConfig;
+exports.shouldFire = shouldFire;
+exports.buildAdvisory = buildAdvisory;
+exports.runContextProbe = runContextProbe;
+exports.runContextCheck = runContextCheck;
+exports.runContext = runContext;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const session_id_1 = require("../session-id");
+const project_anchor_1 = require("../project-anchor");
+exports.DEFAULT_CONTEXT_THRESHOLD = 400_000;
+/** Advisory fires at most once per this many turns — never nag every turn. */
+exports.FIRE_WINDOW_TURNS = 25;
+/** Tail window read from the transcript. The latest assistant entry always
+ *  lives in the last few KB; 64KB gives slack for huge tool_result lines. */
+exports.TAIL_BYTES = 64 * 1024;
+/** Compute the live context size from a chunk of transcript-tail text.
+ *  Walks the JSONL lines BACKWARDS for the most recent main-chain assistant
+ *  entry carrying `message.usage` — sidechain (subagent) entries are skipped,
+ *  as are unparseable lines (the tail cut can land mid-line). Returns null
+ *  when no qualifying entry is in the window. */
+function computeContextSizeFromTail(tailText) {
+    const lines = tailText.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].trim();
+        if (!line)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.isSidechain === true)
+            continue;
+        const msg = (entry.message || {});
+        const role = (msg.role || entry.type || '');
+        if (role !== 'assistant')
+            continue;
+        const usage = msg.usage;
+        if (!usage || typeof usage !== 'object')
+            continue;
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+        const input = num(usage.input_tokens);
+        const cacheRead = num(usage.cache_read_input_tokens);
+        const cacheCreation = num(usage.cache_creation_input_tokens);
+        const tokens = input + cacheRead + cacheCreation;
+        if (tokens <= 0)
+            continue;
+        return {
+            tokens,
+            timestamp: typeof entry.timestamp === 'string' ? entry.timestamp : null,
+        };
+    }
+    return null;
+}
+/** Read the last `maxBytes` of a file. Never parses the whole transcript —
+ *  a marathon session's JSONL runs to tens of MB. Returns null on any error. */
+function readTranscriptTail(transcriptPath, maxBytes = exports.TAIL_BYTES) {
+    let fd = null;
+    try {
+        const { size } = fs.statSync(transcriptPath);
+        const start = Math.max(0, size - maxBytes);
+        const len = size - start;
+        if (len <= 0)
+            return '';
+        fd = fs.openSync(transcriptPath, 'r');
+        const buf = Buffer.alloc(len);
+        fs.readSync(fd, buf, 0, len, start);
+        return buf.toString('utf-8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** State dir — env override (tests) > ~/.greprag/context-state. */
+function contextStateDir() {
+    const override = process.env.GREPRAG_CONTEXT_STATE_DIR;
+    if (override)
+        return override;
+    return path.join(os.homedir(), '.greprag', 'context-state');
+}
+function contextStatePath(shortSessionId) {
+    const safe = shortSessionId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+    return path.join(contextStateDir(), `${safe}.json`);
+}
+function readGovernorState(shortSessionId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(contextStatePath(shortSessionId), 'utf-8'));
+        if (typeof parsed?.tokens !== 'number' || typeof parsed?.turn !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeGovernorState(shortSessionId, state) {
+    try {
+        const file = contextStatePath(shortSessionId);
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+    }
+    catch { /* best-effort — the governor never blocks a turn */ }
+}
+function parseBoolEnv(raw) {
+    if (!raw)
+        return null;
+    if (/^(1|true|yes|on)$/i.test(raw))
+        return true;
+    if (/^(0|false|no|off)$/i.test(raw))
+        return false;
+    return null;
+}
+/** Resolve governor config. Precedence: env > anchor file > defaults.
+ *  Reads the anchor file raw for the context_* keys so the governor stays
+ *  self-contained (no ProjectAnchor type change — additive for the chip seam). */
+function readGovernorConfig(cwd) {
+    let enabled = true;
+    let threshold = exports.DEFAULT_CONTEXT_THRESHOLD;
+    try {
+        const anchor = (0, project_anchor_1.readAnchor)(cwd);
+        const raw = JSON.parse(fs.readFileSync(anchor.anchorPath, 'utf-8'));
+        if (raw.context_governor === false)
+            enabled = false;
+        if (typeof raw.context_threshold === 'number' && raw.context_threshold > 0) {
+            threshold = raw.context_threshold;
+        }
+    }
+    catch { /* no anchor file — defaults stand */ }
+    const envEnabled = parseBoolEnv(process.env.GREPRAG_CONTEXT_GOVERNOR);
+    if (envEnabled !== null)
+        enabled = envEnabled;
+    const envThreshold = Number(process.env.GREPRAG_CONTEXT_THRESHOLD);
+    if (Number.isFinite(envThreshold) && envThreshold > 0)
+        threshold = envThreshold;
+    return { enabled, threshold };
+}
+// ---------- Threshold + advisory (pure) -------------------------------------
+/** Fire when over threshold AND outside the once-per-window sentinel. */
+function shouldFire(state, threshold, windowTurns = exports.FIRE_WINDOW_TURNS) {
+    if (state.tokens <= threshold)
+        return false;
+    if (typeof state.lastFiredTurn !== 'number')
+        return true;
+    return state.turn - state.lastFiredTurn >= windowTurns;
+}
+function buildAdvisory(tokens, threshold) {
+    const n = Math.round(tokens / 1000);
+    const t = Math.round(threshold / 1000);
+    // The snippet (greprag archive snippet) is the governed instruction block —
+    // PreCompact hooks cannot inject compaction instructions, so the operator
+    // carries them via /compact <snippet>. adr: adr/governed-compact.md
+    return `CONTEXT-GOVERNOR: context ~${n}K — past the ${t}K crossover; `
+        + `governed compact recommended at the next natural break `
+        + `(\`greprag archive snippet\` prints the governed /compact instruction block).`;
+}
+/** Stop probe — measure + record. Silent; never blocks the turn. */
+function runContextProbe(input) {
+    const cwd = input.cwd || process.cwd();
+    const cfg = readGovernorConfig(cwd);
+    if (!cfg.enabled)
+        return;
+    const short = (0, session_id_1.truncateSessionId)(input.session_id);
+    if (!short || !input.transcript_path)
+        return;
+    const tail = readTranscriptTail(input.transcript_path);
+    if (tail === null)
+        return;
+    const usage = computeContextSizeFromTail(tail);
+    if (!usage)
+        return;
+    const prev = readGovernorState(short);
+    const state = {
+        tokens: usage.tokens,
+        turn: (prev?.turn ?? 0) + 1,
+        ts: new Date().toISOString(),
+    };
+    if (typeof prev?.lastFiredTurn === 'number')
+        state.lastFiredTurn = prev.lastFiredTurn;
+    writeGovernorState(short, state);
+}
+/** UserPromptSubmit check — returns the advisory line when it should fire
+ *  (and stamps the sentinel), else null. Caller wraps it in hook JSON. */
+function runContextCheck(input) {
+    const cwd = input.cwd || process.cwd();
+    const cfg = readGovernorConfig(cwd);
+    if (!cfg.enabled)
+        return null;
+    const short = (0, session_id_1.truncateSessionId)(input.session_id);
+    if (!short)
+        return null;
+    const state = readGovernorState(short);
+    if (!state)
+        return null;
+    if (!shouldFire(state, cfg.threshold))
+        return null;
+    writeGovernorState(short, { ...state, lastFiredTurn: state.turn });
+    return buildAdvisory(state.tokens, cfg.threshold);
+}
+// ---------- CLI: greprag context status --------------------------------------
+const CONTEXT_HELP = `greprag context — live context-size governor (crossover advisory).
+
+  greprag context status [--session <8hex>]   Current session's context size,
+                                              threshold, % consumed, and turns
+                                              since the advisory last fired.
+
+The governor is hook-driven: a Stop probe records context size from the
+transcript tail; a UserPromptSubmit check injects a one-line advisory once
+the size crosses the threshold (default ${exports.DEFAULT_CONTEXT_THRESHOLD / 1000}K — the cache-read crossover),
+at most once per ${exports.FIRE_WINDOW_TURNS} turns.
+
+Config (.greprag/project.json):
+  "context_governor": false       Disable for this project.
+  "context_threshold": 300000     Override the fire threshold (tokens).
+Env overrides: GREPRAG_CONTEXT_GOVERNOR=off, GREPRAG_CONTEXT_THRESHOLD=<n>.
+`;
+function getFlag(args, name) {
+    const idx = args.indexOf(name);
+    if (idx === -1 || idx + 1 >= args.length)
+        return null;
+    return args[idx + 1];
+}
+function runContext(args) {
+    const sub = args[0];
+    if (sub === '--help' || sub === 'help' || sub === '-h') {
+        console.log(CONTEXT_HELP);
+        return;
+    }
+    if (sub !== 'status' && sub !== undefined) {
+        console.error(`Unknown subcommand: context ${sub}\n`);
+        console.log(CONTEXT_HELP);
+        process.exit(1);
+    }
+    const rawSession = getFlag(args, '--session')
+        || process.env.CLAUDE_CODE_SESSION_ID
+        || process.env.CLAUDE_SESSION_ID
+        || process.env.GREPRAG_SESSION_ID
+        || '';
+    const short = (0, session_id_1.truncateSessionId)(rawSession);
+    if (!short) {
+        console.error('No session id available. Pass --session <8hex>, or run inside a Claude Code session.');
+        process.exit(1);
+    }
+    const cfg = readGovernorConfig(process.cwd());
+    const state = readGovernorState(short);
+    console.log(`Context governor — session ${short}`);
+    console.log(`  Governor:    ${cfg.enabled ? 'enabled' : 'DISABLED'}`);
+    console.log(`  Threshold:   ${(cfg.threshold / 1000).toFixed(0)}K tokens`
+        + (cfg.threshold === exports.DEFAULT_CONTEXT_THRESHOLD ? ' (default)' : ''));
+    if (!state) {
+        console.log('  Context:     (no probe data yet — fires on the next Stop event)');
+        return;
+    }
+    const pct = ((state.tokens / cfg.threshold) * 100).toFixed(0);
+    console.log(`  Context:     ~${(state.tokens / 1000).toFixed(1)}K tokens (as of ${state.ts})`);
+    console.log(`  Consumed:    ${pct}% of threshold`);
+    console.log(`  Turn:        ${state.turn} (probe count this session)`);
+    if (typeof state.lastFiredTurn === 'number') {
+        const since = state.turn - state.lastFiredTurn;
+        console.log(`  Advisory:    last fired at turn ${state.lastFiredTurn} (${since} turn${since === 1 ? '' : 's'} ago; window ${exports.FIRE_WINDOW_TURNS})`);
+    }
+    else {
+        console.log(`  Advisory:    never fired`);
+    }
+}
+//# sourceMappingURL=context-governor.js.map

package/dist/commands/context-governor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-governor.js","sourceRoot":"","sources":["../../src/commands/context-governor.ts"],"names":[],"mappings":"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"}

package/dist/commands/crush-stats.d.ts

@@ -0,0 +1,36 @@
+/** Crush stats — the savings ledger for the pipe-wrap hook.
+ *
+ *  `greprag crush --stats` (the flag the pipe-wrap rewrite always includes)
+ *  appends one JSONL record per invocation to ~/.greprag/crush-stats.jsonl:
+ *  { ts, type, bytesIn, bytesOut }. Passthroughs are recorded too
+ *  (bytesOut === bytesIn) so the totals reflect REAL savings, not just the
+ *  wins. `greprag crush stats` reads the log and prints totals + ratios —
+ *  this is how the compression claims get validated with field data.
+ *
+ *  Append is best-effort and never throws: a stats failure must never break
+ *  the crush exit-0 pipe contract.
+ */
+export interface CrushStatRecord {
+    ts: string;
+    type: string;
+    bytesIn: number;
+    bytesOut: number;
+}
+/** Log file — env override (tests) > ~/.greprag/crush-stats.jsonl. */
+export declare function crushStatsPath(): string;
+/** Append one record. Best-effort: any failure is swallowed. */
+export declare function appendCrushStat(rec: CrushStatRecord): void;
+/** Read every parseable record; bad lines are skipped, missing file = []. */
+export declare function readCrushStats(): CrushStatRecord[];
+export interface CrushStatsBucket {
+    count: number;
+    bytesIn: number;
+    bytesOut: number;
+}
+export interface CrushStatsSummary {
+    total: CrushStatsBucket;
+    byType: Record<string, CrushStatsBucket>;
+}
+export declare function summarizeCrushStats(records: CrushStatRecord[]): CrushStatsSummary;
+/** `greprag crush stats` — print totals + per-type ratios from the log. */
+export declare function runCrushStats(_args: string[]): void;

package/dist/commands/crush-stats.js

@@ -0,0 +1,142 @@
+"use strict";
+// adr: adr/pipe-wrap-hook.md
+/** Crush stats — the savings ledger for the pipe-wrap hook.
+ *
+ *  `greprag crush --stats` (the flag the pipe-wrap rewrite always includes)
+ *  appends one JSONL record per invocation to ~/.greprag/crush-stats.jsonl:
+ *  { ts, type, bytesIn, bytesOut }. Passthroughs are recorded too
+ *  (bytesOut === bytesIn) so the totals reflect REAL savings, not just the
+ *  wins. `greprag crush stats` reads the log and prints totals + ratios —
+ *  this is how the compression claims get validated with field data.
+ *
+ *  Append is best-effort and never throws: a stats failure must never break
+ *  the crush exit-0 pipe contract.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.crushStatsPath = crushStatsPath;
+exports.appendCrushStat = appendCrushStat;
+exports.readCrushStats = readCrushStats;
+exports.summarizeCrushStats = summarizeCrushStats;
+exports.runCrushStats = runCrushStats;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** Log file — env override (tests) > ~/.greprag/crush-stats.jsonl. */
+function crushStatsPath() {
+    return process.env.GREPRAG_CRUSH_STATS
+        || path.join(os.homedir(), '.greprag', 'crush-stats.jsonl');
+}
+/** Append one record. Best-effort: any failure is swallowed. */
+function appendCrushStat(rec) {
+    try {
+        const file = crushStatsPath();
+        const dir = path.dirname(file);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(file, JSON.stringify(rec) + '\n');
+    }
+    catch { /* stats must never break the pipe */ }
+}
+/** Read every parseable record; bad lines are skipped, missing file = []. */
+function readCrushStats() {
+    let raw;
+    try {
+        raw = fs.readFileSync(crushStatsPath(), 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const rec = JSON.parse(trimmed);
+            if (typeof rec?.bytesIn === 'number' && typeof rec?.bytesOut === 'number') {
+                out.push(rec);
+            }
+        }
+        catch { /* skip bad line */ }
+    }
+    return out;
+}
+function summarizeCrushStats(records) {
+    const total = { count: 0, bytesIn: 0, bytesOut: 0 };
+    const byType = {};
+    for (const r of records) {
+        total.count++;
+        total.bytesIn += r.bytesIn;
+        total.bytesOut += r.bytesOut;
+        const b = (byType[r.type] ||= { count: 0, bytesIn: 0, bytesOut: 0 });
+        b.count++;
+        b.bytesIn += r.bytesIn;
+        b.bytesOut += r.bytesOut;
+    }
+    return { total, byType };
+}
+function fmtKb(bytes) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+}
+function fmtRatio(bytesIn, bytesOut) {
+    if (bytesOut <= 0 || bytesIn <= 0)
+        return '—';
+    return `${(bytesIn / bytesOut).toFixed(1)}x`;
+}
+function fmtSavedPct(bytesIn, bytesOut) {
+    if (bytesIn <= 0)
+        return '—';
+    return `${(((bytesIn - bytesOut) / bytesIn) * 100).toFixed(0)}%`;
+}
+/** `greprag crush stats` — print totals + per-type ratios from the log. */
+function runCrushStats(_args) {
+    const records = readCrushStats();
+    console.log(`Crush stats — ${crushStatsPath()}`);
+    if (records.length === 0) {
+        console.log('  (no records yet — the pipe-wrap hook logs one line per crushed command)');
+        return;
+    }
+    const { total, byType } = summarizeCrushStats(records);
+    for (const [type, b] of Object.entries(byType).sort()) {
+        console.log(`  ${type.padEnd(7)} ${String(b.count).padStart(5)} runs   `
+            + `in ${fmtKb(b.bytesIn).padStart(10)}   out ${fmtKb(b.bytesOut).padStart(10)}   `
+            + `${fmtRatio(b.bytesIn, b.bytesOut)} (${fmtSavedPct(b.bytesIn, b.bytesOut)} saved)`);
+    }
+    console.log(`  ${'TOTAL'.padEnd(7)} ${String(total.count).padStart(5)} runs   `
+        + `in ${fmtKb(total.bytesIn).padStart(10)}   out ${fmtKb(total.bytesOut).padStart(10)}   `
+        + `${fmtRatio(total.bytesIn, total.bytesOut)} (${fmtSavedPct(total.bytesIn, total.bytesOut)} saved)`);
+}
+//# sourceMappingURL=crush-stats.js.map

package/dist/commands/crush-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crush-stats.js","sourceRoot":"","sources":["../../src/commands/crush-stats.ts"],"names":[],"mappings":"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"}

package/dist/commands/crush.d.ts

@@ -0,0 +1,24 @@
+/** greprag crush / greprag retrieve — pre-LLM tool-output compression.
+ *
+ *  `greprag crush --type <log|search|json> [--ccr] [--query "words"]`
+ *  reads stdin, writes crushed output to stdout. Designed to sit inside
+ *  users' piped commands, so the contract is HARD:
+ *
+ *  - Exit 0 ALWAYS, even on internal error (pass stdin through verbatim).
+ *  - Token-validate-or-revert: if crushed output isn't fewer estimated
+ *    tokens than the input, emit the input unchanged.
+ *  - Below-threshold skip: log/search < 500B, json < 1KB pass through.
+ *  - With --ccr: the ORIGINAL is stored in the local CCR store
+ *    (~/.greprag/ccr.db; override GREPRAG_CCR_DB) and a trailing
+ *    `<<ccr:HASH>>` marker (first 16 hex of sha256) is appended.
+ *
+ *  `greprag retrieve <hash>` prints the stored original to stdout.
+ *
+ *  Compressors come from the local crush mirror (canonical source:
+ *  packages/core/src/crush — the CLI cannot import @greprag/core).
+ */
+export declare const CRUSH_HELP = "greprag crush \u2014 compress tool output before it reaches the model.\n\nUsage:\n  <command> | greprag crush --type <log|search|json> [--ccr] [--query \"words\"] [--stats]\n  greprag crush stats\n  greprag retrieve <hash>\n\nReads stdin, writes the crushed version to stdout.\n\nFlags:\n  --type <log|search|json>   What the input is:\n                               log     build/test output (pytest, npm, cargo, jest, make)\n                               search  grep/ripgrep output (file:line:content)\n                               json    JSON containing large arrays\n  --ccr                      Stash the ORIGINAL in the local CCR store and append\n                             a trailing <<ccr:HASH>> marker. Recover the full\n                             output later with: greprag retrieve <hash>\n  --query \"words\"            Relevance hint \u2014 matches containing these words\n                             score higher and survive compression (search/json).\n  --stats                    Append { ts, type, bytesIn, bytesOut } to the local\n                             stats log (~/.greprag/crush-stats.jsonl; override\n                             GREPRAG_CRUSH_STATS). Read it back with:\n                             greprag crush stats\n\nContract (safe inside pipes):\n  - ALWAYS exits 0; on any internal error stdin passes through verbatim.\n  - If compression wouldn't save tokens, the input passes through unchanged.\n  - Small inputs (log/search < 500B, json < 1KB) pass through untouched.\n\nCCR store: ~/.greprag/ccr.db (override with GREPRAG_CCR_DB).\n\nExamples:\n  npm test 2>&1 | greprag crush --type log --ccr\n  rg -n \"handleSms\" | greprag crush --type search --query \"handleSms tenant\"\n  curl -s api/items | greprag crush --type json";
+/** greprag crush — exit 0 always; on any failure stdin passes through. */
+export declare function runCrush(args: string[]): Promise<void>;
+/** greprag retrieve <hash> — print a CCR-stored original to stdout. */
+export declare function runRetrieve(args: string[]): Promise<void>;