squeezr-ai 1.81.2 → 1.99.2

package/dist/__tests__/relevance.test.js

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest';
+import { tokenize, bm25Scores, rankByRelevance } from '../relevance.js';
+describe('tokenize', () => {
+    it('lowercases and splits on non-alphanumerics', () => {
+        expect(tokenize('Foo.Bar(baz)')).toEqual(['foo', 'bar', 'baz']);
+    });
+    it('drops 1-char noise tokens but keeps numbers/identifiers', () => {
+        expect(tokenize('a in the db_pool 42')).toEqual(['in', 'the', 'db_pool', '42']);
+    });
+    it('returns [] for empty/symbol-only input', () => {
+        expect(tokenize('   %%$$  ')).toEqual([]);
+    });
+});
+describe('bm25Scores', () => {
+    it('scores a matching doc above a non-matching one', () => {
+        const docs = ['the database connection failed', 'the cat sat on the mat'];
+        const s = bm25Scores('database connection', docs);
+        expect(s[0]).toBeGreaterThan(s[1]);
+    });
+    it('weights a RARE query term more than a common one (idf)', () => {
+        // "apple" appears in 1 doc (rare), "banana" in 3 (common). A doc matching the
+        // rare term should outscore a doc matching only the common one.
+        const docs = ['apple', 'banana', 'banana', 'banana'];
+        const s = bm25Scores('apple banana', docs);
+        expect(s[0]).toBeGreaterThan(s[1]);
+    });
+    it('returns all-zero scores when the query has no usable terms', () => {
+        const docs = ['anything here', 'and here'];
+        expect(bm25Scores('', docs)).toEqual([0, 0]);
+        expect(bm25Scores('%%%', docs)).toEqual([0, 0]);
+    });
+    it('gives a non-matching doc a score of 0', () => {
+        const docs = ['relevant match here', 'totally unrelated'];
+        const s = bm25Scores('relevant', docs);
+        expect(s[1]).toBe(0);
+        expect(s[0]).toBeGreaterThan(0);
+    });
+    it('does not let a long repetitive doc dominate unboundedly (length normalization)', () => {
+        const short = 'error';
+        const long = ('error ' + 'filler '.repeat(200)).trim();
+        const s = bm25Scores('error', [short, long]);
+        // the concise doc that is mostly the query term should score at least as high
+        expect(s[0]).toBeGreaterThanOrEqual(s[1]);
+    });
+    it('is deterministic', () => {
+        const docs = ['alpha beta', 'beta gamma', 'gamma delta'];
+        expect(bm25Scores('beta gamma', docs)).toEqual(bm25Scores('beta gamma', docs));
+    });
+    it('produces one score per doc', () => {
+        const docs = ['a b c', 'd e f', 'g h i'];
+        expect(bm25Scores('a', docs).length).toBe(3);
+    });
+});
+describe('rankByRelevance', () => {
+    it('returns document indices sorted by descending relevance', () => {
+        const docs = ['no match', 'strong error error match', 'weak error'];
+        const order = rankByRelevance('error', docs);
+        expect(order[0]).toBe(1); // most "error" hits
+        expect(order[order.length - 1]).toBe(0); // no match last
+    });
+    it('is a stable permutation of all indices', () => {
+        const docs = ['a', 'b', 'c', 'd'];
+        const order = rankByRelevance('a b', docs);
+        expect([...order].sort((x, y) => x - y)).toEqual([0, 1, 2, 3]);
+    });
+});

package/dist/__tests__/secureKeyFile.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/secureKeyFile.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { mkdtempSync, writeFileSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { secureKeyFile } from '../codexMitm.js';
+// Security regression: the CA private key must be locked to the current user.
+// 0o600 is a no-op on Windows, so secureKeyFile applies a per-OS restriction
+// (icacls on Windows, chmod on POSIX). It must never throw — a key we cannot
+// secure is warned about, not fatal — and must leave the file readable by us.
+describe('secureKeyFile', () => {
+    it('secures a key file without throwing and keeps it owner-readable', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'squeezr-key-'));
+        const keyPath = join(dir, 'ca.key');
+        writeFileSync(keyPath, 'PRIVATE-KEY-MATERIAL', { mode: 0o600 });
+        try {
+            expect(() => secureKeyFile(keyPath)).not.toThrow();
+            expect(readFileSync(keyPath, 'utf-8')).toBe('PRIVATE-KEY-MATERIAL');
+            if (process.platform !== 'win32') {
+                // On POSIX the mode must be owner-only (no group/other bits).
+                expect(statSync(keyPath).mode & 0o077).toBe(0);
+            }
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/__tests__/serverBinding.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/serverBinding.test.js

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// Security regression: the main proxy holds the user's API keys and exposes
+// state-changing control endpoints, so it MUST bind to loopback only and never
+// be reachable from the LAN. This guards against silently reverting that fix.
+describe('main proxy loopback binding', () => {
+    const src = readFileSync(fileURLToPath(new URL('../index.ts', import.meta.url)), 'utf-8');
+    it('binds httpServer.listen to 127.0.0.1', () => {
+        expect(src).toMatch(/httpServer\.listen\(\s*PORT\s*,\s*['"]127\.0\.0\.1['"]/);
+    });
+    it('never binds the main proxy to all interfaces', () => {
+        expect(src).not.toMatch(/httpServer\.listen\(\s*PORT\s*,\s*['"]0\.0\.0\.0['"]/);
+        expect(src).not.toMatch(/httpServer\.listen\(\s*PORT\s*,\s*['"]::['"]/);
+        // A two-arg listen(PORT, cb) would bind all interfaces by default — forbid it.
+        expect(src).not.toMatch(/httpServer\.listen\(\s*PORT\s*,\s*\(/);
+    });
+});

package/dist/__tests__/statsOutput.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/statsOutput.test.js

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { Stats } from '../stats.js';
+// recordEcho / recordShaping only mutate in-memory counters (persistence happens on the
+// main record() path), so these tests never touch ~/.squeezr. We assert relative deltas
+// so a pre-existing stats.json baseline doesn't matter.
+describe('Stats output metrics', () => {
+    it('recordEcho updates sample count and average echo', () => {
+        const s = new Stats();
+        const before = s.summary().output;
+        s.recordEcho(0.2);
+        s.recordEcho(0.4);
+        const after = s.summary().output;
+        expect(after.echo_samples).toBe(before.echo_samples + 2);
+        expect(after.avg_echo_pct).toBeGreaterThanOrEqual(0);
+        expect(after.avg_echo_pct).toBeLessThanOrEqual(100);
+    });
+    it('recordShaping counts only the true flags', () => {
+        const s = new Stats();
+        const before = s.summary().output;
+        s.recordShaping(true, false); // steered only
+        s.recordShaping(true, true); // steered + effort
+        s.recordShaping(false, false); // neither
+        const after = s.summary().output;
+        expect(after.steered).toBe(before.steered + 2);
+        expect(after.effort_lowered).toBe(before.effort_lowered + 1);
+    });
+    it('avg echo reflects the mean of the samples added', () => {
+        const s = new Stats();
+        // add a large batch so any baseline is diluted toward our known mean
+        for (let i = 0; i < 200; i++)
+            s.recordEcho(0.3);
+        expect(Math.abs(s.summary().output.avg_echo_pct - 30)).toBeLessThan(10);
+    });
+    it('recordBypassed counts separately and never touches processed/saved totals', () => {
+        const s = new Stats();
+        const before = s.summary();
+        s.recordBypassed();
+        s.recordBypassed();
+        const after = s.summary();
+        expect(after.bypassed_requests).toBe(before.bypassed_requests + 2);
+        // bypassed traffic must NOT inflate processed or saved
+        expect(after.total_original_chars).toBe(before.total_original_chars);
+        expect(after.total_saved_chars).toBe(before.total_saved_chars);
+        expect(after.requests).toBe(before.requests);
+    });
+});

package/dist/__tests__/textCrusher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/textCrusher.test.js

@@ -0,0 +1,133 @@
+import { describe, it, expect } from 'vitest';
+import { crushText, normalizeLineKey, wordShingles, jaccard } from '../textCrusher.js';
+describe('normalizeLineKey', () => {
+    it('collapses numbers, hex and timestamps so near-duplicates share a key', () => {
+        const a = normalizeLineKey('2026-07-21T10:00:01Z downloaded chunk 12 (0x1a2b)');
+        const b = normalizeLineKey('2026-07-21T11:22:33Z downloaded chunk 998 (0xff00)');
+        expect(a).toBe(b);
+    });
+    it('keeps genuinely different lines distinct', () => {
+        expect(normalizeLineKey('connecting to db')).not.toBe(normalizeLineKey('closing db handle'));
+    });
+});
+describe('crushText', () => {
+    function repetitiveLog(n) {
+        const lines = [];
+        for (let i = 0; i < n; i++)
+            lines.push(`[worker] processed record ${i} in ${i * 2}ms`);
+        return lines.join('\n');
+    }
+    it('returns short input unchanged', () => {
+        const input = 'line a\nline b\nline c';
+        expect(crushText(input, { maxLines: 60 }).text).toBe(input);
+    });
+    it('collapses near-duplicate lines that differ only in numbers', () => {
+        const input = repetitiveLog(200);
+        const res = crushText(input);
+        expect(res.dropped).toBeGreaterThan(0);
+        expect(res.text.length).toBeLessThan(input.length);
+        expect(res.text.split('\n').length).toBeLessThan(200);
+    });
+    it('always keeps lines carrying error/failure signal', () => {
+        const lines = [];
+        for (let i = 0; i < 150; i++)
+            lines.push(`[worker] processed record ${i} ok`);
+        lines.splice(75, 0, 'ERROR: database connection refused at db.example.com:5432');
+        const input = lines.join('\n');
+        const res = crushText(input);
+        expect(res.text.includes('ERROR: database connection refused at db.example.com:5432')).toBe(true);
+    });
+    it('keeps head and tail anchor lines', () => {
+        const lines = ['FIRST LINE MARKER'];
+        for (let i = 0; i < 150; i++)
+            lines.push(`noise line ${i} value ${i}`);
+        lines.push('LAST LINE MARKER');
+        const input = lines.join('\n');
+        const res = crushText(input, { headKeep: 3, tailKeep: 3 });
+        expect(res.text.includes('FIRST LINE MARKER')).toBe(true);
+        expect(res.text.includes('LAST LINE MARKER')).toBe(true);
+    });
+    it('respects the maxLines budget (plus the omitted-summary line)', () => {
+        const res = crushText(repetitiveLog(500), { maxLines: 40 });
+        // kept content lines should not wildly exceed the budget
+        expect(res.text.split('\n').length).toBeLessThanOrEqual(45);
+    });
+    it('preserves the original order of kept lines', () => {
+        const lines = ['alpha unique', ...Array.from({ length: 100 }, (_, i) => `dup ${i}`), 'omega unique'];
+        const res = crushText(lines.join('\n'), { headKeep: 2, tailKeep: 2 });
+        const idxA = res.text.indexOf('alpha unique');
+        const idxO = res.text.indexOf('omega unique');
+        expect(idxA).toBeGreaterThanOrEqual(0);
+        expect(idxO).toBeGreaterThan(idxA);
+    });
+    it('is deterministic', () => {
+        const input = repetitiveLog(300);
+        expect(crushText(input).text).toBe(crushText(input).text);
+    });
+    it('emits an omitted-count marker when it drops lines', () => {
+        const res = crushText(repetitiveLog(300));
+        expect(/\[\d+ lines omitted/.test(res.text)).toBe(true);
+    });
+    it('with a query, keeps task-relevant lines that a blind pass would drop', () => {
+        // 120 noise lines + one line mentioning the task keyword, positioned in the middle
+        // (not an anchor) so only relevance can save it.
+        const lines = [];
+        for (let i = 0; i < 60; i++)
+            lines.push(`background chore ${i} finished`);
+        lines.push('updated the authentication middleware token refresh logic');
+        for (let i = 0; i < 60; i++)
+            lines.push(`background chore ${i + 60} finished`);
+        const input = lines.join('\n');
+        const withQuery = crushText(input, { maxLines: 20, headKeep: 3, tailKeep: 3, query: 'authentication middleware token' });
+        expect(withQuery.text.includes('authentication middleware token refresh')).toBe(true);
+    });
+    it('stays deterministic for a fixed query', () => {
+        const input = repetitiveLog(300);
+        const a = crushText(input, { query: 'record ms' }).text;
+        const b = crushText(input, { query: 'record ms' }).text;
+        expect(a).toBe(b);
+    });
+    it('collapses REWORDED near-duplicate lines (not just number-varied)', () => {
+        // Two wordings of the same idea, no numbers, no signal keywords → exact-key dedup
+        // would keep both; shingle near-dup should collapse them.
+        const a = 'the worker finished processing the batch quickly and moved on';
+        const b = 'the worker completed processing the batch quickly and moved on';
+        // Unique anchor lines at head/tail (no "worker") so the variants live in the MIDDLE,
+        // where the budget-fill + shingle collapse applies.
+        const lines = ['ALPHA HEADER ONE', 'ALPHA HEADER TWO', 'ALPHA HEADER THREE'];
+        for (let i = 0; i < 100; i++)
+            lines.push(i % 2 === 0 ? a : b);
+        lines.push('OMEGA FOOTER ONE', 'OMEGA FOOTER TWO', 'OMEGA FOOTER THREE');
+        const res = crushText(lines.join('\n'), { maxLines: 30, headKeep: 3, tailKeep: 3 });
+        const distinct = new Set(res.text.split('\n').filter(l => l.includes('worker')));
+        // both wordings collapse to (at most) one representative
+        expect(distinct.size).toBeLessThanOrEqual(1);
+    });
+    it('does NOT collapse genuinely different lines', () => {
+        const lines = ['UNIQUE HEADER'];
+        for (let i = 0; i < 30; i++) {
+            lines.push('alpha subsystem initialised the primary cache layer');
+            lines.push('gamma module rejected the inbound websocket handshake');
+        }
+        lines.push('UNIQUE FOOTER');
+        const res = crushText(lines.join('\n'), { maxLines: 40, headKeep: 2, tailKeep: 2 });
+        expect(res.text.includes('alpha subsystem')).toBe(true);
+        expect(res.text.includes('gamma module')).toBe(true);
+    });
+});
+describe('wordShingles / jaccard', () => {
+    it('reworded lines share most shingles (high jaccard)', () => {
+        const a = wordShingles('the worker finished processing the batch quickly');
+        const b = wordShingles('the worker completed processing the batch quickly');
+        expect(jaccard(a, b)).toBeGreaterThan(0.4);
+    });
+    it('unrelated lines share few shingles (low jaccard)', () => {
+        const a = wordShingles('database connection pool exhausted');
+        const b = wordShingles('the cat sat on the warm mat');
+        expect(jaccard(a, b)).toBeLessThan(0.1);
+    });
+    it('identical lines have jaccard 1', () => {
+        const a = wordShingles('exactly the same words here now');
+        expect(jaccard(a, a)).toBe(1);
+    });
+});

package/dist/bench.d.ts

@@ -0,0 +1,45 @@
+/**
+ * squeezr bench — honest, reproducible compression+accuracy harness.
+ *
+ * Headroom's headline claim is "same answers, fewer tokens", proven by having an LLM
+ * answer questions over compressed data. That needs an API key and costs money, so it
+ * can't live in CI. This harness measures the same thing with a zero-cost, deterministic
+ * proxy for accuracy: FACT RECALL.
+ *
+ * For each fixture we declare the CRITICAL FACTS an answer would need (an error code, a
+ * filename, a specific value, a count). We compress the fixture through Squeezr's real
+ * deterministic pipeline and measure:
+ *
+ *   - compressionPct — chars removed / original chars.
+ *   - inlineRecall    — fraction of critical facts still present VERBATIM in the compressed
+ *                       output (i.e. answerable WITHOUT an expand round-trip).
+ *
+ * Recoverability is 100% by design (every compressed block stores its original in the
+ * expand store — see expand.test.ts), so the meaningful, honest metric is how much
+ * survives inline. A fixture that trades recall for ratio (huge-log head/tail) shows it
+ * here rather than hiding it.
+ */
+export interface Fixture {
+    name: string;
+    tool: string;
+    content: string;
+    facts: string[];
+}
+export interface BenchRow {
+    name: string;
+    originalChars: number;
+    compressedChars: number;
+    compressionPct: number;
+    inlineRecall: number;
+}
+export interface BenchSummary {
+    rows: BenchRow[];
+    avgCompressionPct: number;
+    avgInlineRecall: number;
+}
+/** Fraction of `facts` present verbatim in `text`. Empty fact list → 1 (nothing to lose). */
+export declare function factRecall(text: string, facts: string[]): number;
+export declare const FIXTURES: Fixture[];
+export declare function runBench(fixtures?: Fixture[]): BenchSummary;
+/** Human-readable table for the CLI. */
+export declare function formatBench(summary: BenchSummary): string;

package/dist/bench.js

@@ -0,0 +1,114 @@
+/**
+ * squeezr bench — honest, reproducible compression+accuracy harness.
+ *
+ * Headroom's headline claim is "same answers, fewer tokens", proven by having an LLM
+ * answer questions over compressed data. That needs an API key and costs money, so it
+ * can't live in CI. This harness measures the same thing with a zero-cost, deterministic
+ * proxy for accuracy: FACT RECALL.
+ *
+ * For each fixture we declare the CRITICAL FACTS an answer would need (an error code, a
+ * filename, a specific value, a count). We compress the fixture through Squeezr's real
+ * deterministic pipeline and measure:
+ *
+ *   - compressionPct — chars removed / original chars.
+ *   - inlineRecall    — fraction of critical facts still present VERBATIM in the compressed
+ *                       output (i.e. answerable WITHOUT an expand round-trip).
+ *
+ * Recoverability is 100% by design (every compressed block stores its original in the
+ * expand store — see expand.test.ts), so the meaningful, honest metric is how much
+ * survives inline. A fixture that trades recall for ratio (huge-log head/tail) shows it
+ * here rather than hiding it.
+ */
+import { preprocessForTool } from './deterministic.js';
+/** Fraction of `facts` present verbatim in `text`. Empty fact list → 1 (nothing to lose). */
+export function factRecall(text, facts) {
+    if (facts.length === 0)
+        return 1;
+    const present = facts.filter(f => text.includes(f)).length;
+    return present / facts.length;
+}
+// ── Fixtures ─────────────────────────────────────────────────────────────────
+function jsonArrayFixture() {
+    const rows = [];
+    for (let i = 0; i < 40; i++) {
+        rows.push({ id: i, service: `svc-${i}`, status: i === 17 ? 'CrashLoopBackOff' : 'Running', restarts: i === 17 ? 42 : 0, node: 'ip-10-0-1-5' });
+    }
+    return JSON.stringify(rows);
+}
+function buildLogFixture() {
+    const lines = [];
+    for (let i = 0; i < 60; i++)
+        lines.push('[webpack] compiling module... ok');
+    lines.push('ERROR in ./src/app.ts:128:14');
+    lines.push("TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.");
+    for (let i = 0; i < 60; i++)
+        lines.push('[webpack] compiling module... ok');
+    return lines.join('\n');
+}
+function grepFixture() {
+    const lines = [];
+    for (let f = 0; f < 30; f++) {
+        for (let l = 0; l < 5; l++)
+            lines.push(`src/mod${f}.ts:${l + 1}: const value = computeThing(${l})`);
+    }
+    lines.push('src/critical.ts:99: throw new FatalError("DISK_FULL")');
+    return lines.join('\n');
+}
+export const FIXTURES = [
+    {
+        name: 'json-array (k8s pods)',
+        tool: 'Bash',
+        content: jsonArrayFixture(),
+        // The one anomalous row an answer would need + its schema.
+        facts: ['CrashLoopBackOff', '42', 'svc-17', 'ip-10-0-1-5'],
+    },
+    {
+        name: 'build-log (tsc error in noise)',
+        tool: 'Bash',
+        content: buildLogFixture(),
+        facts: ['TS2345', './src/app.ts:128:14'],
+    },
+    {
+        name: 'grep-dump (fatal among matches)',
+        tool: 'Grep',
+        content: grepFixture(),
+        facts: ['DISK_FULL', 'src/critical.ts:99'],
+    },
+];
+// ── Runner ───────────────────────────────────────────────────────────────────
+export function runBench(fixtures = FIXTURES) {
+    const rows = fixtures.map(f => {
+        const compressed = preprocessForTool(f.content, f.tool, 0);
+        const originalChars = f.content.length;
+        const compressedChars = compressed.length;
+        const compressionPct = originalChars > 0 ? Math.max(0, ((originalChars - compressedChars) / originalChars) * 100) : 0;
+        return {
+            name: f.name,
+            originalChars,
+            compressedChars,
+            compressionPct: Math.round(compressionPct * 10) / 10,
+            inlineRecall: factRecall(compressed, f.facts),
+        };
+    });
+    const n = rows.length || 1;
+    return {
+        rows,
+        avgCompressionPct: Math.round((rows.reduce((s, r) => s + r.compressionPct, 0) / n) * 10) / 10,
+        avgInlineRecall: Math.round((rows.reduce((s, r) => s + r.inlineRecall, 0) / n) * 100) / 100,
+    };
+}
+/** Human-readable table for the CLI. */
+export function formatBench(summary) {
+    const lines = [];
+    lines.push('Squeezr compression + fact-recall benchmark');
+    lines.push('(recoverability is 100% by design via squeezr_expand; inline recall = answerable without expanding)');
+    lines.push('');
+    lines.push('fixture                              orig    comp   saved   inline-recall');
+    lines.push('─'.repeat(78));
+    for (const r of summary.rows) {
+        lines.push(`${r.name.padEnd(36)} ${String(r.originalChars).padStart(6)} ${String(r.compressedChars).padStart(6)} ${(r.compressionPct + '%').padStart(6)}   ${Math.round(r.inlineRecall * 100) + '%'}`);
+    }
+    lines.push('─'.repeat(78));
+    lines.push(`AVG: ${summary.avgCompressionPct}% compression · ${Math.round(summary.avgInlineRecall * 100)}% inline fact recall · 100% recoverable`);
+    return lines.join('\n');
+}

package/dist/cacheAligner.d.ts

@@ -0,0 +1,34 @@
+/**
+ * CacheAligner (detector-only) — Squeezr's take on headroom's CacheAligner.
+ *
+ * Anthropic bills the cached prefix at 0.1x, but ONLY if the prefix arrives byte-for-byte
+ * identical between requests. If the CLIENT's own system prompt embeds volatile content
+ * (a per-session UUID, a live timestamp, a build hash, a JWT) INSIDE the cached region,
+ * that prefix changes every request and the cache never hits — re-billing the whole
+ * context at full price. That is exactly the failure that once burned a 5h plan.
+ *
+ * Squeezr already monitors cache hit-health %; this tells you the likely CAUSE. It is a
+ * pure DETECTOR: it never mutates the prompt (mutating the cache hot zone is itself a
+ * cache-buster). It just surfaces "your prefix is unstable because of X".
+ *
+ * Detection is structural (shape-based regex over known volatile token forms), not
+ * semantic. Order matters: JWTs are matched before hashes so a JWT segment isn't
+ * miscounted as a hex hash.
+ */
+export type VolatileKind = 'uuid' | 'timestamp' | 'jwt' | 'hash';
+export interface VolatileFinding {
+    kind: VolatileKind;
+    count: number;
+}
+/** Structural scan for volatile tokens. Matched kinds are masked out before later
+ *  patterns run, so a JWT is never also counted as a hash. */
+export declare function detectVolatile(text: string): VolatileFinding[];
+export interface SystemAnalysis {
+    hasVolatile: boolean;
+    findings: VolatileFinding[];
+}
+export declare function analyzeSystemPrompt(system: unknown): SystemAnalysis;
+export declare function formatVolatileWarning(findings: VolatileFinding[]): string;
+/** Warn at most once per distinct finding signature. Returns true iff it warned now. */
+export declare function warnIfVolatile(system: unknown): boolean;
+export declare function _resetWarnedForTest(): void;

package/dist/cacheAligner.js

@@ -0,0 +1,73 @@
+/**
+ * CacheAligner (detector-only) — Squeezr's take on headroom's CacheAligner.
+ *
+ * Anthropic bills the cached prefix at 0.1x, but ONLY if the prefix arrives byte-for-byte
+ * identical between requests. If the CLIENT's own system prompt embeds volatile content
+ * (a per-session UUID, a live timestamp, a build hash, a JWT) INSIDE the cached region,
+ * that prefix changes every request and the cache never hits — re-billing the whole
+ * context at full price. That is exactly the failure that once burned a 5h plan.
+ *
+ * Squeezr already monitors cache hit-health %; this tells you the likely CAUSE. It is a
+ * pure DETECTOR: it never mutates the prompt (mutating the cache hot zone is itself a
+ * cache-buster). It just surfaces "your prefix is unstable because of X".
+ *
+ * Detection is structural (shape-based regex over known volatile token forms), not
+ * semantic. Order matters: JWTs are matched before hashes so a JWT segment isn't
+ * miscounted as a hex hash.
+ */
+const PATTERNS = [
+    { kind: 'jwt', re: /\beyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\b/g },
+    { kind: 'uuid', re: /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi },
+    { kind: 'timestamp', re: /\b\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?Z?\b/g },
+    { kind: 'hash', re: /\b[0-9a-f]{40}\b|\b[0-9a-f]{64}\b/gi },
+];
+/** Structural scan for volatile tokens. Matched kinds are masked out before later
+ *  patterns run, so a JWT is never also counted as a hash. */
+export function detectVolatile(text) {
+    let scan = text;
+    const findings = [];
+    for (const { kind, re } of PATTERNS) {
+        const matches = scan.match(re);
+        if (matches && matches.length > 0) {
+            findings.push({ kind, count: matches.length });
+            scan = scan.replace(re, ' '); // mask so subsequent, looser patterns don't re-match
+        }
+    }
+    return findings;
+}
+function systemToText(system) {
+    if (typeof system === 'string')
+        return system;
+    if (Array.isArray(system)) {
+        return system
+            .filter(b => b && b.type === 'text' && typeof b.text === 'string')
+            .map(b => b.text)
+            .join('\n');
+    }
+    return '';
+}
+export function analyzeSystemPrompt(system) {
+    const findings = detectVolatile(systemToText(system));
+    return { hasVolatile: findings.length > 0, findings };
+}
+export function formatVolatileWarning(findings) {
+    const parts = findings.map(f => `${f.count}× ${f.kind}`).join(', ');
+    return `[squeezr/cache-aligner] system prompt contains volatile content (${parts}) — if it sits inside the cached prefix it will bust Anthropic's prompt cache every request. Squeezr never mutates the prefix; consider moving volatile tokens after the cache_control breakpoint.`;
+}
+// ── Throttled warning (no per-request spam) ──────────────────────────────────
+const warned = new Set();
+/** Warn at most once per distinct finding signature. Returns true iff it warned now. */
+export function warnIfVolatile(system) {
+    const { hasVolatile, findings } = analyzeSystemPrompt(system);
+    if (!hasVolatile)
+        return false;
+    const sig = findings.map(f => `${f.kind}:${f.count}`).sort().join('|');
+    if (warned.has(sig))
+        return false;
+    warned.add(sig);
+    console.log(formatVolatileWarning(findings));
+    return true;
+}
+export function _resetWarnedForTest() {
+    warned.clear();
+}

package/dist/codexMitm.d.ts

@@ -1,4 +1,5 @@
 export declare const BUNDLE_PATH: string;
 export declare const MITM_PORT: number;
+export declare function secureKeyFile(path: string): void;
 export declare function startMitmProxy(): void;
 export declare function stopMitmProxy(): void;

package/dist/codexMitm.js

@@ -4,7 +4,8 @@ import http from 'node:http';
 import https from 'node:https';
 import fs from 'node:fs';
 import crypto from 'node:crypto';
-import { homedir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { homedir, userInfo } from 'node:os';
 import { join } from 'node:path';
 import forge from 'node-forge';
 import { config } from './config.js';
@@ -15,6 +16,26 @@ const CA_CERT_PATH = join(CA_DIR, 'ca.crt');
 export const BUNDLE_PATH = join(CA_DIR, 'bundle.crt');
 export const MITM_PORT = config.mitmPort;
 // ── CA generation ─────────────────────────────────────────────────────────────
+// POSIX permission bits (0o600) are ignored on Windows, so the CA private key
+// would be left readable by other accounts. Lock it down per-OS: an ACL that
+// grants only the current user on Windows, chmod 0o600 on POSIX. A private key
+// we cannot secure is a real risk, so failure is surfaced loudly, never silent.
+export function secureKeyFile(path) {
+    if (process.platform === 'win32') {
+        const user = process.env.USERNAME || userInfo().username;
+        try {
+            // /inheritance:r drops inherited ACEs; /grant:r sets the current user as
+            // the only principal with Full control.
+            execFileSync('icacls', [path, '/inheritance:r', '/grant:r', `${user}:F`], { stdio: 'ignore' });
+        }
+        catch (err) {
+            console.warn(`[squeezr/mitm] WARNING: could not restrict permissions on ${path} — ` +
+                `${err.message}. Secure this private key manually.`);
+        }
+        return;
+    }
+    fs.chmodSync(path, 0o600);
+}
 function ensureCA() {
     const certsExist = fs.existsSync(CA_KEY_PATH) && fs.existsSync(CA_CERT_PATH);
     if (!certsExist) {
@@ -35,6 +56,7 @@ function ensureCA() {
         ]);
         cert.sign(keys.privateKey, forge.md.sha256.create());
         fs.writeFileSync(CA_KEY_PATH, forge.pki.privateKeyToPem(keys.privateKey), { mode: 0o600 });
+        secureKeyFile(CA_KEY_PATH);
         fs.writeFileSync(CA_CERT_PATH, forge.pki.certificateToPem(cert), { mode: 0o644 });
         console.log(`[squeezr/mitm] CA generated → ${CA_CERT_PATH}`);
     }
@@ -438,7 +460,9 @@ export function startMitmProxy() {
         if (err.code !== 'EADDRINUSE')
             console.error('[squeezr/mitm] error:', err.message);
     });
-    mitmServer.listen(MITM_PORT, () => {
+    // Loopback only: the MITM proxy terminates TLS for the user's traffic and must
+    // never be reachable from the LAN (matches the other listeners).
+    mitmServer.listen(MITM_PORT, '127.0.0.1', () => {
         console.log(`[squeezr/mitm] HTTPS proxy on http://localhost:${MITM_PORT}`);
     });
 }