@raquezha/noheadroom 0.3.1 → 0.3.3

package/README.md

@@ -1,28 +1,21 @@
 # noheadroom 🗜
 
-> **Reclaim your Pi context window.** A local-first context compression bridge for the Pi Coding Agent, powered by [Headroom](https://github.com/headroom-ai/headroom).
+> **Reclaim your Pi context window.** A local-first context compression bridge for the Pi Coding Agent, powered by [Headroom](https://github.com/headroomlabs-ai/headroom).
 
 `noheadroom` sits between Pi and your LLM, using Headroom to shrink massive tool outputs/results and logs before they become model input. Headroom itself is a general prompt/context compression engine that can transform broader request material. `noheadroom` deliberately applies a stricter Pi policy: user prompts and assistant messages may be sent as context for the compression request, but Pi only accepts mutations to `toolResult` content. User chat, assistant text, tool-call metadata, and tool IDs remain unchanged in real Pi history. Save tokens, keep more history, and prevent context-overflow in long sessions.
 
 ## 🚀 Why noheadroom?
 
-Upstream Headroom protects common agent tool names like `read` and `bash` by default. In a standard Pi workflow, this means large file reads often bypass compression entirely.
-
-`noheadroom` adapts the compression payload to bypass these exclusions while **fully preserving your Pi session metadata**.
-
-| Setup | Tool Name | Headroom Action | Savings |
-|---|---|---|---|
-| Vanilla | `read` | `excluded_tool` | 0% |
-| **noheadroom** | `read` | `smart_crusher` | **60-90%** |
+Headroom intentionally protects file reads: changing source text can break exact-match edits. `noheadroom` keeps those reads raw and compresses eligible large text-only tool results (for example, repetitive logs). It never changes the stored Pi session transcript.
 
 ## ✨ Features
 
 - **Headroom Bridge, Pi Policy**: Headroom can optimize broad prompt/context payloads; `noheadroom` intentionally narrows what gets applied back to Pi so only `toolResult` content mutates.
-- **Adaptive Payload Sanitization**: renames tool calls during compression to ensure Headroom actually shrinks them.
-- **Strict Candidate Isolation**: limits applied mutations strictly to `toolResult` messages, safely ignoring upstream proxy mangling of user/assistant history to prevent false-positive guard skips.
-- **Turn-by-Turn Loop Prevention**: caches eligible `toolResult` candidate fingerprints using tool identity, content shape, length, and stable content hashes to block useless proxy retries across new conversational turns while still retrying when actual tool output changes.
+- **Tool Fidelity**: preserves tool names and arguments so Headroom's protected-tool policy remains effective.
+- **Strict Candidate Isolation**: applies only eligible text-only, non-error `toolResult` changes; rejects retrieval markers without a registered retrieval tool.
+- **Request-local Replay**: reuses validated compression for the same tool call and unchanged result on later model requests without re-calling the proxy. A new tool call with the same output remains raw to avoid re-read loops.
 - **Pi-Native Metadata Preservation**: original tool IDs and names are never modified in your real session.
-- **Deep Visibility**: compression results appear in your terminal, the Pi footer, and as persistent entries in your session history.
+- **Visibility**: session-local compression estimates appear in the terminal and Pi footer; proxy `/stats` does not count extension `/v1/compress` requests as inference savings.
 - **Docker-First Architecture**: designed to work seamlessly with a local containerized backend.
 - **Local-First Privacy**: by default, context never leaves your machine.
 

package/dist/bridge.d.ts

@@ -5,8 +5,7 @@ type AnyMessage = AgentMessage & {
     timestamp?: number;
 };
 export declare function buildCompressionPayload(messages: AgentMessage[], minMessageChars: number): CompressionPayload;
-export declare function applyCompressionResult(originalMessages: AgentMessage[], mappings: CompressionMapping[], compressedMessages: OpenAIMessage[], _options: ApplyCompressionOptions): ApplyCompressionResult;
+export declare function applyCompressionResult(originalMessages: AgentMessage[], mappings: CompressionMapping[], compressedMessages: OpenAIMessage[], options: ApplyCompressionOptions): ApplyCompressionResult;
 export declare function convertMessage(message: AnyMessage): OpenAIMessage | undefined;
 export declare function extractOpenAIText(message: OpenAIMessage): string;
-export declare function injectCompressionAwareness(messages: AgentMessage[]): AgentMessage[];
 export {};

package/dist/bridge.js

@@ -1,4 +1,7 @@
 const STANDARD_COMPRESSIBLE_ROLES = new Set(["user", "assistant", "toolResult"]);
+// File reads supply exact edit anchors; directives and recovered evidence must stay raw.
+const PROTECTED_TOOLS = new Set(["read", "read_file", "view", "edit", "write", "skill", "headroom_retrieve"]);
+const CCR_MARKER = /Retrieve\s+(?:more|original):\s*hash=|<<ccr:/i;
 export function buildCompressionPayload(messages, minMessageChars) {
     const mappings = [];
     let candidateCount = 0;
@@ -10,13 +13,19 @@ export function buildCompressionPayload(messages, minMessageChars) {
         const originalText = extractOpenAIText(converted);
         // Mark candidates for compression.
         // ONLY toolResults are candidates, preserving original Pi conversation fidelity.
-        let applyTo = source.role === "toolResult" ? "toolResult" : null;
+        const textOnly = typeof source.content === "string" ||
+            (Array.isArray(source.content) && source.content.every(isTextContent));
+        let applyTo = source.role === "toolResult" &&
+            textOnly && originalText.length >= minMessageChars &&
+            !("isError" in source && source.isError) &&
+            !PROTECTED_TOOLS.has((readStringProperty(source, "toolName") ?? "").toLowerCase())
+            ? "toolResult" : null;
         // Headroom Bypass Rules (Android Hat)
         // We never want to compress `android layout` JSON dumps or critical adb dumps.
         if (source.role === "toolResult" && originalText.trim().startsWith("[") && originalText.includes('"resource-id"')) {
             applyTo = null;
         }
-        if (applyTo && originalText.length >= minMessageChars)
+        if (applyTo)
             candidateCount++;
         mappings.push({ sourceIndex, message: converted, applyTo, originalText });
     }
@@ -26,38 +35,59 @@ export function buildCompressionPayload(messages, minMessageChars) {
         candidateCount,
     };
 }
-export function applyCompressionResult(originalMessages, mappings, compressedMessages, _options) {
-    if (compressedMessages.length !== mappings.length) {
+export function applyCompressionResult(originalMessages, mappings, compressedMessages, options) {
+    if (!Array.isArray(compressedMessages) || compressedMessages.length !== mappings.length) {
         return { ok: false, reason: "message-count-changed" };
     }
     const nextMessages = structuredClone(originalMessages);
     let appliedMessages = 0;
+    let appliedTokensBefore = 0;
+    let appliedTokensAfter = 0;
     for (let index = 0; index < mappings.length; index++) {
         const mapping = mappings[index];
         const compressed = compressedMessages[index];
         // We only validate and apply changes to explicit candidates.
         // Headroom is allowed to mangle non-candidates (like assistant history) in its output,
         // but we simply ignore those changes and keep the original Pi message intact.
-        if (!mapping.applyTo)
+        if (!mapping.applyTo || mapping.originalText.length < options.minMessageChars)
             continue;
         const validation = validateAlignedMessage(mapping.message, compressed);
         if (!validation.ok)
             return validation;
-        let nextText = extractOpenAIText(compressed);
+        const nextText = extractOpenAIText(compressed);
         if (nextText === mapping.originalText)
             continue;
-        // Naturalize Headroom's native CCR markers to provide Pi-native tooling hints (Upstream #846)
-        nextText = naturalizeHeadroomMarkers(nextText);
+        // No retrieval executor is registered. Hiding a hash does not recover evidence.
+        if (CCR_MARKER.test(nextText))
+            return { ok: false, reason: "unrecoverable-ccr-marker" };
+        if (!nextText.trim())
+            return { ok: false, reason: "empty-compressed-content" };
+        if (estimateTokens(nextText) >= estimateTokens(mapping.originalText))
+            continue;
         const target = nextMessages[mapping.sourceIndex];
         if (!hasContent(target) || !replaceTextContent(target, nextText)) {
             return { ok: false, reason: "target-content-unreplaceable" };
         }
+        appliedTokensBefore += estimateTokens(mapping.originalText);
+        appliedTokensAfter += estimateTokens(nextText);
         appliedMessages++;
     }
     if (appliedMessages === 0) {
         return { ok: false, reason: "no-applicable-message-changed" };
     }
-    return { ok: true, messages: nextMessages, appliedMessages };
+    const appliedTokensSaved = Math.max(0, appliedTokensBefore - appliedTokensAfter);
+    if (appliedTokensSaved === 0) {
+        return { ok: false, reason: "no-estimated-token-savings" };
+    }
+    return {
+        ok: true,
+        messages: nextMessages,
+        appliedMessages,
+        appliedTokensBefore,
+        appliedTokensAfter,
+        appliedTokensSaved,
+        appliedCompressionRatio: appliedTokensAfter / appliedTokensBefore,
+    };
 }
 export function convertMessage(message) {
     if (!message.role || !STANDARD_COMPRESSIBLE_ROLES.has(message.role))
@@ -126,14 +156,16 @@ function convertToolCall(toolCall) {
         id: toolCall.id,
         type: "function",
         function: {
-            // Headroom protects exact tool names (read, bash) in its DEFAULT_EXCLUDE_TOOLS.
-            // Keep upstream bridge behavior until tests prove a better name changes routing/fidelity.
-            name: "pi_tool_result",
-            arguments: JSON.stringify({ originalToolName: toolCall.name }),
+            // Preserve upstream tool protections as well as routing context.
+            name: toolCall.name,
+            arguments: JSON.stringify(toolCall.arguments),
         },
     };
 }
 function validateAlignedMessage(original, compressed) {
+    if (!isRecord(compressed) || (original.role === "tool" && typeof compressed.content !== "string")) {
+        return { ok: false, reason: "invalid-compressed-message" };
+    }
     if (original.role !== compressed.role) {
         return { ok: false, reason: `role-changed:${original.role}->${compressed.role}` };
     }
@@ -221,24 +253,7 @@ function readStringProperty(value, key) {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
-function naturalizeHeadroomMarkers(text) {
-    // Translate Headroom's "[X items compressed to Y. Retrieve more: hash=...]" 
-    // into a Pi-native instruction to use offset/limit instead of hallucinating a retrieve command.
-    return text.replace(/\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve more: hash=[a-f0-9]+\]/gi, "[$1. Hint: Do not re-read the whole file. Use the 'read' tool with 'offset' and 'limit' to inspect specific sections.]");
-}
-export function injectCompressionAwareness(messages) {
-    // If a system message already exists at the top, we append the hint to it.
-    // Otherwise, we inject a new system message at index 0.
-    const result = [...messages];
-    const hintText = "Environment Hint: Some tool results in this context have been automatically compressed by Headroom to optimize tokens. If you see '[X items compressed to Y]' or similar markers, do NOT attempt to re-read the entire file. Use the 'read' tool with 'offset' and 'limit' to query missing sections.";
-    const first = result[0];
-    if (first && first.role === "system" && typeof first.content === "string") {
-        if (!first.content.includes("automatically compressed by Headroom")) {
-            result[0] = { ...first, content: `${first.content}\n\n${hintText}` };
-        }
-    }
-    else {
-        result.unshift({ role: "system", content: hintText });
-    }
-    return result;
+function estimateTokens(text) {
+    // ponytail: cheap local estimate; exact tokenizer would add a heavy dependency for a footer number.
+    return text.length === 0 ? 0 : Math.max(1, Math.ceil(text.length / 4));
 }

package/dist/client.js

@@ -8,14 +8,13 @@ export class HeadroomHttpClient {
     async health(signal) {
         try {
             const response = await fetch(`${this.baseUrl}/health`, {
+                redirect: "error",
                 signal: buildSignal(this.timeoutMs, signal),
             });
             if (!response.ok)
                 return false;
             const body = await readJsonObject(response);
-            if (!body)
-                return true;
-            return body.status === "healthy" || body.status === "ok" || "optimize" in body || "stats" in body;
+            return Boolean(body && body.ready !== false && (body.status === "healthy" || body.status === "ok"));
         }
         catch {
             return false;
@@ -24,12 +23,16 @@ export class HeadroomHttpClient {
     async probe(signal) {
         try {
             const response = await fetch(`${this.baseUrl}/v1/compress`, {
+                redirect: "error",
                 method: "POST",
                 headers: { "Content-Type": "application/json" },
                 body: JSON.stringify({ messages: [{ role: "user", content: "ping" }], model: "gpt-4o" }),
                 signal: buildSignal(5_000, signal),
             });
-            return response.ok;
+            if (!response.ok)
+                return false;
+            validateCompressionResponse(await response.json());
+            return true;
         }
         catch {
             return false;
@@ -37,6 +40,7 @@ export class HeadroomHttpClient {
     }
     async stats(signal) {
         const response = await fetch(`${this.baseUrl}/stats`, {
+            redirect: "error",
             signal: buildSignal(this.timeoutMs, signal),
         });
         if (!response.ok) {
@@ -46,19 +50,25 @@ export class HeadroomHttpClient {
     }
     async compress(messages, model, signal) {
         const response = await fetch(`${this.baseUrl}/v1/compress`, {
+            redirect: "error",
             method: "POST",
             headers: {
                 "Content-Type": "application/json",
                 "X-Headroom-Stack": "pi-extension",
             },
-            body: JSON.stringify({ messages, model: model || "gpt-4o" }),
+            body: JSON.stringify({
+                messages,
+                model: model || "gpt-4o",
+                // 0.39.1's default is marker-free and inherits the backend's --lossless policy.
+                // lossy_inline would override that policy and enable lossy SmartCrusher.
+            }),
             signal: buildSignal(this.timeoutMs, signal),
         });
         if (!response.ok) {
             const message = await readErrorMessage(response);
             throw new Error(message || `Headroom /v1/compress failed with HTTP ${response.status}`);
         }
-        const payload = (await response.json());
+        const payload = validateCompressionResponse(await response.json());
         return {
             messages: payload.messages,
             tokensBefore: payload.tokens_before,
@@ -71,6 +81,17 @@ export class HeadroomHttpClient {
         };
     }
 }
+function validateCompressionResponse(value) {
+    const metrics = ["tokens_before", "tokens_after", "tokens_saved", "compression_ratio"];
+    const stringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === "string");
+    if (!isRecord(value) || !Array.isArray(value.messages) ||
+        !metrics.every((key) => typeof value[key] === "number" && Number.isFinite(value[key]) && value[key] >= 0) ||
+        (value.transforms_applied !== undefined && !stringArray(value.transforms_applied)) ||
+        (value.ccr_hashes !== undefined && (!stringArray(value.ccr_hashes) || value.ccr_hashes.length > 0))) {
+        throw new Error("Invalid or retrieval-dependent Headroom compression response");
+    }
+    return value;
+}
 async function readJsonObject(response) {
     try {
         const body = (await response.json());

package/dist/config.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 const DEFAULT_BASE_URL = "http://127.0.0.1:8788";
-const DEFAULT_MIN_CONTEXT_TOKENS = 20_000;
+const DEFAULT_MIN_CONTEXT_TOKENS = 10_000;
 const DEFAULT_MIN_MESSAGE_CHARS = 2_000;
 const DEFAULT_TIMEOUT_MS = 30_000;
 export const HEADROOM_SETTINGS_DIR = path.join(os.homedir(), ".pi", "agent", "headroom");
@@ -48,7 +48,8 @@ export function loadHeadroomConfig(env = process.env, settings = env === process
 export function isLocalHeadroomUrl(rawUrl) {
     try {
         const url = new URL(rawUrl);
-        return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+        return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password &&
+            ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
     }
     catch {
         return false;

package/dist/index.d.ts

@@ -14,6 +14,7 @@ interface HeadroomRuntimeState {
     lastGuardSkipCandidateFingerprint: string | null;
     seenCandidateContentFingerprints?: Set<string>;
     seenCandidateContentOrder?: string[];
+    compressedCandidates?: Map<string, string>;
     lastCompressionTime: number;
     stats: HeadroomStats;
 }

package/dist/index.js

@@ -17,6 +17,14 @@ export default function headroomExtension(pi) {
     registerCompressionRenderer(pi);
     const runtime = createRuntime(pi);
     pi.on("session_start", (_event, ctx) => {
+        // A context transform is request-local; cached substitutions must not cross sessions.
+        runtime.state.compressedCandidates = new Map();
+        runtime.state.seenCandidateContentFingerprints = new Set();
+        runtime.state.seenCandidateContentOrder = [];
+        runtime.state.lastInputFingerprint = null;
+        runtime.state.lastOutputFingerprint = null;
+        runtime.state.lastGuardSkipCandidateFingerprint = null;
+        runtime.state.lastCompressionTime = 0;
         if (isRemoteBlocked(runtime.config)) {
             runtime.refreshStatus(ctx);
             emitNotraceTelemetry(runtime);
@@ -79,6 +87,7 @@ function createRuntime(pi) {
         lastGuardSkipCandidateFingerprint: null,
         seenCandidateContentFingerprints: new Set(),
         seenCandidateContentOrder: [],
+        compressedCandidates: new Map(),
         lastCompressionTime: 0,
         stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
     };
@@ -207,38 +216,42 @@ function registerCompressionRenderer(pi) {
 async function handleContextCompression(runtime, event, ctx) {
     if (runtime.state.processing)
         return undefined;
-    // Throttle: max 1 compression attempt per 3 seconds to kill infinite loops
-    const now = Date.now();
-    if (now - runtime.state.lastCompressionTime < 3000) {
-        return undefined;
-    }
-    // Content-based guards to prevent infinite recursion
-    const inputFingerprint = generateFingerprint(event.messages);
-    // 1. If this input matches our previous output, we already compressed it. Stop.
-    if (runtime.state.lastOutputFingerprint === inputFingerprint) {
-        return undefined;
-    }
-    // 2. If this input matches our previous input, it didn't change. Stop.
-    if (runtime.state.lastInputFingerprint === inputFingerprint) {
-        return undefined;
-    }
+    let replayed;
+    const bypassUncompressed = () => {
+        if (runtime.state.stats.last) {
+            runtime.state.stats.last = undefined;
+            runtime.refreshStatus(ctx);
+        }
+        return replayed ? { messages: replayed } : undefined;
+    };
     if (shouldSkipBeforePayload(runtime, ctx))
-        return undefined;
+        return bypassUncompressed();
     const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
+    replayed = replayCachedCandidates(runtime.state, event.messages, payload, runtime.config.minMessageChars);
     if (payload.candidateCount === 0)
+        return bypassUncompressed();
+    // Pi's context transform is request-local; reuse validated text on later turns.
+    const now = Date.now();
+    if (now - runtime.state.lastCompressionTime < 3000)
+        return bypassUncompressed();
+    const inputFingerprint = generateFingerprint(event.messages);
+    if (runtime.state.lastOutputFingerprint === inputFingerprint)
         return undefined;
+    if (runtime.state.lastInputFingerprint === inputFingerprint)
+        return bypassUncompressed();
     // 3. If eligible candidates haven't changed since the last skip/no-savings result,
     // don't spend another proxy call just because surrounding conversation changed.
     const candidateFingerprint = generateCandidateFingerprint(event.messages, payload);
     if (runtime.state.lastGuardSkipCandidateFingerprint === candidateFingerprint) {
-        return undefined;
+        return bypassUncompressed();
     }
     if (allCandidateContentSeen(runtime.state, payload)) {
-        return undefined;
+        return bypassUncompressed();
     }
+    ignoreSeenCandidateContent(runtime.state, payload);
     if (runtime.state.proxyOnline !== true) {
         void ensureProxyInBackground(runtime, ctx);
-        return undefined;
+        return bypassUncompressed();
     }
     runtime.state.processing = true;
     runtime.state.lastCompressionTime = now;
@@ -251,10 +264,7 @@ async function handleContextCompression(runtime, event, ctx) {
             // until the actual compressible candidate material changes.
             runtime.state.lastInputFingerprint = inputFingerprint;
             runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
-            // ponytail: clear stats.last so renderFooterStatus shows idle instead of stale savings
-            runtime.state.stats.last = undefined;
-            runtime.refreshStatus(ctx);
-            return undefined;
+            return bypassUncompressed();
         }
         const applied = applyCompressionResult(event.messages, payload.mappings, result.messages, {
             minMessageChars: runtime.config.minMessageChars,
@@ -267,28 +277,79 @@ async function handleContextCompression(runtime, event, ctx) {
             recordGuardSkip(runtime.state.stats, applied.reason);
             emitNotraceTelemetry(runtime);
             announceGuardSkip(ctx, applied.reason, result, runtime.config.mode);
-            runtime.refreshStatus(ctx);
-            return undefined;
+            return bypassUncompressed();
         }
         // Store fingerprints to break the feedback loop
         runtime.state.lastInputFingerprint = inputFingerprint;
-        runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
         runtime.state.lastGuardSkipCandidateFingerprint = null;
-        recordSeenCandidateContent(runtime.state, payload, result.messages);
-        recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
+        recordSeenCandidateContent(runtime.state, payload, applied.messages);
+        if (replayed) {
+            for (const mapping of payload.mappings) {
+                if (runtime.state.compressedCandidates?.has(candidateKey(event.messages[mapping.sourceIndex], mapping.originalText))) {
+                    applied.messages[mapping.sourceIndex] = replayed[mapping.sourceIndex];
+                }
+            }
+        }
+        recordCachedCandidates(runtime.state, payload, applied.messages);
+        runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
+        const appliedResult = {
+            ...result,
+            tokensBefore: applied.appliedTokensBefore,
+            tokensAfter: applied.appliedTokensAfter,
+            tokensSaved: applied.appliedTokensSaved,
+            compressionRatio: applied.appliedCompressionRatio,
+        };
+        recordAppliedCompression(runtime.state.stats, appliedResult, applied.appliedMessages);
         emitNotraceTelemetry(runtime);
-        announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages, runtime.config.mode);
+        announceAppliedCompression(runtime.pi, ctx, appliedResult, applied.appliedMessages, runtime.config.mode);
         runtime.refreshStatus(ctx);
         return { messages: applied.messages };
     }
     catch (error) {
         recordCompressionError(runtime, ctx, error);
-        return undefined;
+        return bypassUncompressed();
     }
     finally {
         runtime.state.processing = false;
     }
 }
+function candidateKey(message, text) {
+    const source = message;
+    return stableHash(JSON.stringify([source.toolCallId, source.toolName, stableHash(text)]));
+}
+function replayCachedCandidates(state, messages, payload, minMessageChars) {
+    if (!state.compressedCandidates?.size)
+        return undefined;
+    const mappings = payload.mappings.map((mapping) => ({
+        ...mapping,
+        applyTo: mapping.applyTo && state.compressedCandidates?.has(candidateKey(messages[mapping.sourceIndex], mapping.originalText))
+            ? mapping.applyTo : null,
+    }));
+    const compressed = mappings.map((mapping) => {
+        const text = mapping.applyTo && state.compressedCandidates?.get(candidateKey(messages[mapping.sourceIndex], mapping.originalText));
+        return text && mapping.message.role === "tool" ? { ...mapping.message, content: text } : mapping.message;
+    });
+    const applied = applyCompressionResult(messages, mappings, compressed, { minMessageChars });
+    return applied.ok ? applied.messages : undefined;
+}
+function recordCachedCandidates(state, payload, messages) {
+    state.compressedCandidates ??= new Map();
+    for (const mapping of payload.mappings) {
+        if (!mapping.applyTo)
+            continue;
+        const applied = convertMessage(messages[mapping.sourceIndex]);
+        if (!applied || applied.role !== "tool")
+            continue;
+        const text = extractOpenAIText(applied);
+        if (text === mapping.originalText)
+            continue;
+        const key = candidateKey(messages[mapping.sourceIndex], mapping.originalText);
+        state.compressedCandidates.set(key, text);
+        if (state.compressedCandidates.size > MAX_SEEN_CANDIDATE_CONTENT_FINGERPRINTS) {
+            state.compressedCandidates.delete(state.compressedCandidates.keys().next().value);
+        }
+    }
+}
 function allCandidateContentSeen(state, payload) {
     const seen = state.seenCandidateContentFingerprints;
     if (!seen?.size)
@@ -296,16 +357,25 @@ function allCandidateContentSeen(state, payload) {
     const hashes = payload.mappings.filter((mapping) => mapping.applyTo).map((mapping) => stableHash(mapping.originalText));
     return hashes.length > 0 && hashes.every((hash) => seen.has(hash));
 }
-function recordSeenCandidateContent(state, payload, compressedMessages) {
+function ignoreSeenCandidateContent(state, payload) {
+    const seen = state.seenCandidateContentFingerprints;
+    if (!seen?.size)
+        return;
+    for (const mapping of payload.mappings) {
+        if (mapping.applyTo && seen.has(stableHash(mapping.originalText)))
+            mapping.applyTo = null;
+    }
+}
+function recordSeenCandidateContent(state, payload, appliedMessages) {
     state.seenCandidateContentFingerprints ??= new Set();
     state.seenCandidateContentOrder ??= [];
-    payload.mappings.forEach((mapping, index) => {
+    payload.mappings.forEach((mapping) => {
         if (!mapping.applyTo)
             return;
         addSeenCandidateHash(state, stableHash(mapping.originalText));
-        const compressed = compressedMessages[index];
-        if (compressed)
-            addSeenCandidateHash(state, stableHash(extractOpenAIText(compressed)));
+        const applied = convertMessage(appliedMessages[mapping.sourceIndex]);
+        if (applied)
+            addSeenCandidateHash(state, stableHash(extractOpenAIText(applied)));
     });
 }
 function addSeenCandidateHash(state, hash) {
@@ -391,7 +461,7 @@ function recordAppliedCompression(stats, result, appliedMessages) {
 function summarizeTelemetry(state) {
     if (state.stats.last) {
         const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
-        return `compressed ${state.stats.last.tokensBefore.toLocaleString()} to ${state.stats.last.tokensAfter.toLocaleString()} tokens; saved ${state.stats.last.tokensSaved.toLocaleString()} tokens across ${state.stats.last.appliedMessages} tool results (-${pct}%)`;
+        return `last compression estimated about ${state.stats.last.tokensSaved.toLocaleString()} tokens saved (-${pct}%) across ${state.stats.last.appliedMessages} tool results; local session estimate about ${state.stats.tokensSaved.toLocaleString()} tokens saved`;
     }
     if (!state.enabled)
         return "headroom loaded but disabled for this session";
@@ -443,7 +513,7 @@ function announceAppliedCompression(pi, ctx, result, appliedMessages, mode = "no
     if (mode === "quiet" || mode === "silent")
         return;
     const pct = Math.round((1 - result.compressionRatio) * 100);
-    const summary = `compressed ${result.tokensBefore.toLocaleString()} → ${result.tokensAfter.toLocaleString()} tokens (-${pct}%, saved ${result.tokensSaved.toLocaleString()}, messages ${appliedMessages})`;
+    const summary = `compressed ${appliedMessages} tool results; estimated ~${result.tokensSaved.toLocaleString()} tokens saved (-${pct}%)`;
     const line = `noheadroom: ${summary}`;
     ctx.ui.notify(line, "info");
     // Note: we no longer use pi.appendEntry or pi.sendMessage here because
@@ -561,10 +631,7 @@ function renderFooterStatus(ctx, config, state) {
         return paint("dim", "○ Headroom not running");
     if (state.proxyOnline === null && !state.stats.last)
         return paint("dim", "○ Headroom idle");
-    if (!state.stats.last)
-        return paint("success", "✓") + paint("dim", " Headroom");
-    const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
-    return (paint("success", "✓") + paint("dim", ` Headroom -${pct}% (${state.stats.last.tokensSaved.toLocaleString()} saved)`));
+    return paint("success", "✓") + paint("dim", " Headroom active");
 }
 async function showProxyStats(ctx, client, config) {
     if (isRemoteBlocked(config)) {
@@ -596,7 +663,8 @@ function renderStatus(config, state) {
         `  Attempts:     ${stats.attempts}`,
         `  Applied:      ${stats.applied}`,
         `  Guard skips:  ${stats.guardSkips}`,
-        `  Tokens saved: ${stats.tokensSaved.toLocaleString()}`,
+        `  Estimated tokens saved: ~${stats.tokensSaved.toLocaleString()}`,
+        `  Note: local estimate; proxy /stats does not track Pi extension /v1/compress calls.`,
     ];
     if (stats.last) {
         const pct = Math.round((1 - stats.last.compressionRatio) * 100);

package/dist/proxy-manager.js

@@ -13,27 +13,33 @@ export async function startPersistentHeadroomProxy(config) {
             env: {
                 ...process.env,
                 HEADROOM_TELEMETRY: process.env.HEADROOM_TELEMETRY || "off",
+                HEADROOM_BEACON: process.env.HEADROOM_BEACON || "off",
             },
         });
-        child.unref();
-        return { ok: true };
+        return await new Promise((resolve) => {
+            child.once("error", (error) => resolve({ ok: false, reason: error.message }));
+            child.once("spawn", () => {
+                child.unref();
+                resolve({ ok: true });
+            });
+        });
     }
     catch (error) {
         return { ok: false, reason: error instanceof Error ? error.message : String(error) };
     }
 }
 export function buildProxyArgs(endpoint) {
-    return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "token", "--no-cache"];
+    return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "cache", "--lossless", "--no-cache"];
 }
 export function parseLocalEndpoint(baseUrl) {
     try {
         const url = new URL(baseUrl);
-        if (!["http:", "https:"].includes(url.protocol))
+        if (url.protocol !== "http:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
             return undefined;
         if (!["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname))
             return undefined;
         const host = url.hostname === "localhost" ? "127.0.0.1" : url.hostname.replace(/^\[(.*)]$/, "$1");
-        const port = url.port || "8787";
+        const port = url.port || "80";
         return { host, port };
     }
     catch {

package/dist/types.d.ts

@@ -96,6 +96,10 @@ export type ApplyCompressionResult = {
     ok: true;
     messages: AgentMessage[];
     appliedMessages: number;
+    appliedTokensBefore: number;
+    appliedTokensAfter: number;
+    appliedTokensSaved: number;
+    appliedCompressionRatio: number;
 } | {
     ok: false;
     reason: string;

package/extensions/bridge.ts

@@ -17,6 +17,9 @@ interface MessageWithContent {
 }
 
 const STANDARD_COMPRESSIBLE_ROLES = new Set(["user", "assistant", "toolResult"]);
+// File reads supply exact edit anchors; directives and recovered evidence must stay raw.
+const PROTECTED_TOOLS = new Set(["read", "read_file", "view", "edit", "write", "skill", "headroom_retrieve"]);
+const CCR_MARKER = /Retrieve\s+(?:more|original):\s*hash=|<<ccr:/i;
 
 export function buildCompressionPayload(messages: AgentMessage[], minMessageChars: number): CompressionPayload {
 	const mappings: CompressionMapping[] = [];
@@ -30,7 +33,13 @@ export function buildCompressionPayload(messages: AgentMessage[], minMessageChar
 		const originalText = extractOpenAIText(converted);
 		// Mark candidates for compression.
 		// ONLY toolResults are candidates, preserving original Pi conversation fidelity.
-		let applyTo: "toolResult" | null = source.role === "toolResult" ? "toolResult" : null;
+		const textOnly = typeof source.content === "string" ||
+			(Array.isArray(source.content) && source.content.every(isTextContent));
+		let applyTo: "toolResult" | null = source.role === "toolResult" &&
+			textOnly && originalText.length >= minMessageChars &&
+			!("isError" in source && source.isError) &&
+			!PROTECTED_TOOLS.has((readStringProperty(source, "toolName") ?? "").toLowerCase())
+			? "toolResult" : null;
 
 		// Headroom Bypass Rules (Android Hat)
 		// We never want to compress `android layout` JSON dumps or critical adb dumps.
@@ -38,7 +47,7 @@ export function buildCompressionPayload(messages: AgentMessage[], minMessageChar
 			applyTo = null;
 		}
 		
-		if (applyTo && originalText.length >= minMessageChars) candidateCount++;
+		if (applyTo) candidateCount++;
 		mappings.push({ sourceIndex, message: converted, applyTo, originalText });
 	}
 
@@ -53,14 +62,16 @@ export function applyCompressionResult(
 	originalMessages: AgentMessage[],
 	mappings: CompressionMapping[],
 	compressedMessages: OpenAIMessage[],
-	_options: ApplyCompressionOptions,
+	options: ApplyCompressionOptions,
 ): ApplyCompressionResult {
-	if (compressedMessages.length !== mappings.length) {
+	if (!Array.isArray(compressedMessages) || compressedMessages.length !== mappings.length) {
 		return { ok: false, reason: "message-count-changed" };
 	}
 
 	const nextMessages = structuredClone(originalMessages) as AgentMessage[];
 	let appliedMessages = 0;
+	let appliedTokensBefore = 0;
+	let appliedTokensAfter = 0;
 
 	for (let index = 0; index < mappings.length; index++) {
 		const mapping = mappings[index];
@@ -69,29 +80,44 @@ export function applyCompressionResult(
 		// We only validate and apply changes to explicit candidates.
 		// Headroom is allowed to mangle non-candidates (like assistant history) in its output,
 		// but we simply ignore those changes and keep the original Pi message intact.
-		if (!mapping.applyTo) continue;
+		if (!mapping.applyTo || mapping.originalText.length < options.minMessageChars) continue;
 
 		const validation = validateAlignedMessage(mapping.message, compressed);
 		if (!validation.ok) return validation;
 
-		let nextText = extractOpenAIText(compressed);
+		const nextText = extractOpenAIText(compressed);
 		if (nextText === mapping.originalText) continue;
-
-		// Naturalize Headroom's native CCR markers to provide Pi-native tooling hints (Upstream #846)
-		nextText = naturalizeHeadroomMarkers(nextText);
+		// No retrieval executor is registered. Hiding a hash does not recover evidence.
+		if (CCR_MARKER.test(nextText)) return { ok: false, reason: "unrecoverable-ccr-marker" };
+		if (!nextText.trim()) return { ok: false, reason: "empty-compressed-content" };
+		if (estimateTokens(nextText) >= estimateTokens(mapping.originalText)) continue;
 
 		const target = nextMessages[mapping.sourceIndex] as AnyMessage;
 		if (!hasContent(target) || !replaceTextContent(target, nextText)) {
 			return { ok: false, reason: "target-content-unreplaceable" };
 		}
+		appliedTokensBefore += estimateTokens(mapping.originalText);
+		appliedTokensAfter += estimateTokens(nextText);
 		appliedMessages++;
 	}
 
 	if (appliedMessages === 0) {
 		return { ok: false, reason: "no-applicable-message-changed" };
 	}
+	const appliedTokensSaved = Math.max(0, appliedTokensBefore - appliedTokensAfter);
+	if (appliedTokensSaved === 0) {
+		return { ok: false, reason: "no-estimated-token-savings" };
+	}
 
-	return { ok: true, messages: nextMessages, appliedMessages };
+	return {
+		ok: true,
+		messages: nextMessages,
+		appliedMessages,
+		appliedTokensBefore,
+		appliedTokensAfter,
+		appliedTokensSaved,
+		appliedCompressionRatio: appliedTokensAfter / appliedTokensBefore,
+	};
 }
 
 export function convertMessage(message: AnyMessage): OpenAIMessage | undefined {
@@ -159,10 +185,9 @@ function convertToolCall(toolCall: ToolCall): OpenAIToolCall {
 		id: toolCall.id,
 		type: "function",
 		function: {
-			// Headroom protects exact tool names (read, bash) in its DEFAULT_EXCLUDE_TOOLS.
-			// Keep upstream bridge behavior until tests prove a better name changes routing/fidelity.
-			name: "pi_tool_result",
-			arguments: JSON.stringify({ originalToolName: toolCall.name }),
+			// Preserve upstream tool protections as well as routing context.
+			name: toolCall.name,
+			arguments: JSON.stringify(toolCall.arguments),
 		},
 	};
 }
@@ -171,6 +196,9 @@ function validateAlignedMessage(
 	original: OpenAIMessage,
 	compressed: OpenAIMessage,
 ): { ok: true } | { ok: false; reason: string } {
+	if (!isRecord(compressed) || (original.role === "tool" && typeof compressed.content !== "string")) {
+		return { ok: false, reason: "invalid-compressed-message" };
+	}
 	if (original.role !== compressed.role) {
 		return { ok: false, reason: `role-changed:${original.role}->${compressed.role}` };
 	}
@@ -267,29 +295,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
 
-function naturalizeHeadroomMarkers(text: string): string {
-	// Translate Headroom's "[X items compressed to Y. Retrieve more: hash=...]" 
-	// into a Pi-native instruction to use offset/limit instead of hallucinating a retrieve command.
-	return text.replace(
-		/\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve more: hash=[a-f0-9]+\]/gi,
-		"[$1. Hint: Do not re-read the whole file. Use the 'read' tool with 'offset' and 'limit' to inspect specific sections.]"
-	);
-}
-
-export function injectCompressionAwareness(messages: AgentMessage[]): AgentMessage[] {
-	// If a system message already exists at the top, we append the hint to it.
-	// Otherwise, we inject a new system message at index 0.
-	const result = [...messages];
-	const hintText = "Environment Hint: Some tool results in this context have been automatically compressed by Headroom to optimize tokens. If you see '[X items compressed to Y]' or similar markers, do NOT attempt to re-read the entire file. Use the 'read' tool with 'offset' and 'limit' to query missing sections.";
-
-	const first = result[0] as unknown as Record<string, unknown>;
-	if (first && first.role === "system" && typeof first.content === "string") {
-		if (!first.content.includes("automatically compressed by Headroom")) {
-			result[0] = { ...first, content: `${first.content}\n\n${hintText}` } as unknown as AgentMessage;
-		}
-	} else {
-		result.unshift({ role: "system", content: hintText } as unknown as AgentMessage);
-	}
-
-	return result;
+function estimateTokens(text: string): number {
+	// ponytail: cheap local estimate; exact tokenizer would add a heavy dependency for a footer number.
+	return text.length === 0 ? 0 : Math.max(1, Math.ceil(text.length / 4));
 }

package/extensions/client.ts

@@ -27,12 +27,12 @@ export class HeadroomHttpClient {
 	async health(signal?: AbortSignal): Promise<boolean> {
 		try {
 			const response = await fetch(`${this.baseUrl}/health`, {
+				redirect: "error",
 				signal: buildSignal(this.timeoutMs, signal),
 			});
 			if (!response.ok) return false;
 			const body = await readJsonObject(response);
-			if (!body) return true;
-			return body.status === "healthy" || body.status === "ok" || "optimize" in body || "stats" in body;
+			return Boolean(body && body.ready !== false && (body.status === "healthy" || body.status === "ok"));
 		} catch {
 			return false;
 		}
@@ -41,12 +41,15 @@ export class HeadroomHttpClient {
 	async probe(signal?: AbortSignal): Promise<boolean> {
 		try {
 			const response = await fetch(`${this.baseUrl}/v1/compress`, {
+				redirect: "error",
 				method: "POST",
 				headers: { "Content-Type": "application/json" },
 				body: JSON.stringify({ messages: [{ role: "user", content: "ping" }], model: "gpt-4o" }),
 				signal: buildSignal(5_000, signal),
 			});
-			return response.ok;
+			if (!response.ok) return false;
+			validateCompressionResponse(await response.json());
+			return true;
 		} catch {
 			return false;
 		}
@@ -54,6 +57,7 @@ export class HeadroomHttpClient {
 
 	async stats(signal?: AbortSignal): Promise<unknown> {
 		const response = await fetch(`${this.baseUrl}/stats`, {
+			redirect: "error",
 			signal: buildSignal(this.timeoutMs, signal),
 		});
 		if (!response.ok) {
@@ -64,12 +68,18 @@ export class HeadroomHttpClient {
 
 	async compress(messages: OpenAIMessage[], model: string | undefined, signal?: AbortSignal): Promise<CompressResult> {
 		const response = await fetch(`${this.baseUrl}/v1/compress`, {
+			redirect: "error",
 			method: "POST",
 			headers: {
 				"Content-Type": "application/json",
 				"X-Headroom-Stack": "pi-extension",
 			},
-			body: JSON.stringify({ messages, model: model || "gpt-4o" }),
+			body: JSON.stringify({
+				messages,
+				model: model || "gpt-4o",
+				// 0.39.1's default is marker-free and inherits the backend's --lossless policy.
+				// lossy_inline would override that policy and enable lossy SmartCrusher.
+			}),
 			signal: buildSignal(this.timeoutMs, signal),
 		});
 
@@ -78,7 +88,7 @@ export class HeadroomHttpClient {
 			throw new Error(message || `Headroom /v1/compress failed with HTTP ${response.status}`);
 		}
 
-		const payload = (await response.json()) as ProxyCompressResponse;
+		const payload = validateCompressionResponse(await response.json());
 		return {
 			messages: payload.messages,
 			tokensBefore: payload.tokens_before,
@@ -92,6 +102,18 @@ export class HeadroomHttpClient {
 	}
 }
 
+function validateCompressionResponse(value: unknown): ProxyCompressResponse {
+	const metrics = ["tokens_before", "tokens_after", "tokens_saved", "compression_ratio"];
+	const stringArray = (v: unknown) => Array.isArray(v) && v.every((item) => typeof item === "string");
+	if (!isRecord(value) || !Array.isArray(value.messages) ||
+		!metrics.every((key) => typeof value[key] === "number" && Number.isFinite(value[key]) && value[key] >= 0) ||
+		(value.transforms_applied !== undefined && !stringArray(value.transforms_applied)) ||
+		(value.ccr_hashes !== undefined && (!stringArray(value.ccr_hashes) || (value.ccr_hashes as string[]).length > 0))) {
+		throw new Error("Invalid or retrieval-dependent Headroom compression response");
+	}
+	return value as unknown as ProxyCompressResponse;
+}
+
 async function readJsonObject(response: Response): Promise<Record<string, unknown> | undefined> {
 	try {
 		const body = (await response.json()) as unknown;

package/extensions/config.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import type { HeadroomConfig, HeadroomMode } from "./types.js";
 
 const DEFAULT_BASE_URL = "http://127.0.0.1:8788";
-const DEFAULT_MIN_CONTEXT_TOKENS = 20_000;
+const DEFAULT_MIN_CONTEXT_TOKENS = 10_000;
 const DEFAULT_MIN_MESSAGE_CHARS = 2_000;
 const DEFAULT_TIMEOUT_MS = 30_000;
 
@@ -84,7 +84,8 @@ export function loadHeadroomConfig(
 export function isLocalHeadroomUrl(rawUrl: string): boolean {
 	try {
 		const url = new URL(rawUrl);
-		return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
+		return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password &&
+			["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname);
 	} catch {
 		return false;
 	}

package/extensions/index.ts

@@ -36,6 +36,7 @@ interface HeadroomRuntimeState {
 	lastGuardSkipCandidateFingerprint: string | null;
 	seenCandidateContentFingerprints?: Set<string>;
 	seenCandidateContentOrder?: string[];
+	compressedCandidates?: Map<string, string>;
 	lastCompressionTime: number;
 	stats: HeadroomStats;
 }
@@ -67,6 +68,14 @@ export default function headroomExtension(pi: ExtensionAPI) {
 	const runtime = createRuntime(pi);
 
 	pi.on("session_start", (_event, ctx) => {
+		// A context transform is request-local; cached substitutions must not cross sessions.
+		runtime.state.compressedCandidates = new Map();
+		runtime.state.seenCandidateContentFingerprints = new Set();
+		runtime.state.seenCandidateContentOrder = [];
+		runtime.state.lastInputFingerprint = null;
+		runtime.state.lastOutputFingerprint = null;
+		runtime.state.lastGuardSkipCandidateFingerprint = null;
+		runtime.state.lastCompressionTime = 0;
 		if (isRemoteBlocked(runtime.config)) {
 			runtime.refreshStatus(ctx);
 			emitNotraceTelemetry(runtime);
@@ -135,6 +144,7 @@ function createRuntime(pi: ExtensionAPI): HeadroomRuntime {
 		lastGuardSkipCandidateFingerprint: null,
 		seenCandidateContentFingerprints: new Set(),
 		seenCandidateContentOrder: [],
+		compressedCandidates: new Map(),
 		lastCompressionTime: 0,
 		stats: { attempts: 0, applied: 0, guardSkips: 0, tokensSaved: 0 },
 	};
@@ -270,41 +280,40 @@ async function handleContextCompression(
 ): Promise<{ messages?: AgentMessage[] } | undefined> {
 	if (runtime.state.processing) return undefined;
 
-	// Throttle: max 1 compression attempt per 3 seconds to kill infinite loops
-	const now = Date.now();
-	if (now - runtime.state.lastCompressionTime < 3000) {
-		return undefined;
-	}
-
-	// Content-based guards to prevent infinite recursion
-	const inputFingerprint = generateFingerprint(event.messages);
-
-	// 1. If this input matches our previous output, we already compressed it. Stop.
-	if (runtime.state.lastOutputFingerprint === inputFingerprint) {
-		return undefined;
-	}
-
-	// 2. If this input matches our previous input, it didn't change. Stop.
-	if (runtime.state.lastInputFingerprint === inputFingerprint) {
-		return undefined;
-	}
+	let replayed: AgentMessage[] | undefined;
+	const bypassUncompressed = () => {
+		if (runtime.state.stats.last) {
+			runtime.state.stats.last = undefined;
+			runtime.refreshStatus(ctx);
+		}
+		return replayed ? { messages: replayed } : undefined;
+	};
 
-	if (shouldSkipBeforePayload(runtime, ctx)) return undefined;
+	if (shouldSkipBeforePayload(runtime, ctx)) return bypassUncompressed();
 	const payload = buildCompressionPayload(event.messages, runtime.config.minMessageChars);
-	if (payload.candidateCount === 0) return undefined;
+	replayed = replayCachedCandidates(runtime.state, event.messages, payload, runtime.config.minMessageChars);
+	if (payload.candidateCount === 0) return bypassUncompressed();
+
+	// Pi's context transform is request-local; reuse validated text on later turns.
+	const now = Date.now();
+	if (now - runtime.state.lastCompressionTime < 3000) return bypassUncompressed();
+	const inputFingerprint = generateFingerprint(event.messages);
+	if (runtime.state.lastOutputFingerprint === inputFingerprint) return undefined;
+	if (runtime.state.lastInputFingerprint === inputFingerprint) return bypassUncompressed();
 
 	// 3. If eligible candidates haven't changed since the last skip/no-savings result,
 	// don't spend another proxy call just because surrounding conversation changed.
 	const candidateFingerprint = generateCandidateFingerprint(event.messages, payload);
 	if (runtime.state.lastGuardSkipCandidateFingerprint === candidateFingerprint) {
-		return undefined;
+		return bypassUncompressed();
 	}
 	if (allCandidateContentSeen(runtime.state, payload)) {
-		return undefined;
+		return bypassUncompressed();
 	}
+	ignoreSeenCandidateContent(runtime.state, payload);
 	if (runtime.state.proxyOnline !== true) {
 		void ensureProxyInBackground(runtime, ctx);
-		return undefined;
+		return bypassUncompressed();
 	}
 
 	runtime.state.processing = true;
@@ -318,10 +327,7 @@ async function handleContextCompression(
 			// until the actual compressible candidate material changes.
 			runtime.state.lastInputFingerprint = inputFingerprint;
 			runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
-			// ponytail: clear stats.last so renderFooterStatus shows idle instead of stale savings
-			runtime.state.stats.last = undefined;
-			runtime.refreshStatus(ctx);
-			return undefined;
+			return bypassUncompressed();
 		}
 
 		const applied = applyCompressionResult(event.messages, payload.mappings, result.messages, {
@@ -336,29 +342,81 @@ async function handleContextCompression(
 			recordGuardSkip(runtime.state.stats, applied.reason);
 			emitNotraceTelemetry(runtime);
 			announceGuardSkip(ctx, applied.reason, result, runtime.config.mode);
-			runtime.refreshStatus(ctx);
-			return undefined;
+			return bypassUncompressed();
 		}
 
 		// Store fingerprints to break the feedback loop
 		runtime.state.lastInputFingerprint = inputFingerprint;
-		runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
 		runtime.state.lastGuardSkipCandidateFingerprint = null;
-		recordSeenCandidateContent(runtime.state, payload, result.messages);
-
-		recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
+		recordSeenCandidateContent(runtime.state, payload, applied.messages);
+		if (replayed) {
+			for (const mapping of payload.mappings) {
+				if (runtime.state.compressedCandidates?.has(candidateKey(event.messages[mapping.sourceIndex], mapping.originalText))) {
+					applied.messages[mapping.sourceIndex] = replayed[mapping.sourceIndex];
+				}
+			}
+		}
+		recordCachedCandidates(runtime.state, payload, applied.messages);
+		runtime.state.lastOutputFingerprint = generateFingerprint(applied.messages);
+		const appliedResult = {
+			...result,
+			tokensBefore: applied.appliedTokensBefore,
+			tokensAfter: applied.appliedTokensAfter,
+			tokensSaved: applied.appliedTokensSaved,
+			compressionRatio: applied.appliedCompressionRatio,
+		};
+
+		recordAppliedCompression(runtime.state.stats, appliedResult, applied.appliedMessages);
 		emitNotraceTelemetry(runtime);
-		announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages, runtime.config.mode);
+		announceAppliedCompression(runtime.pi, ctx, appliedResult, applied.appliedMessages, runtime.config.mode);
 		runtime.refreshStatus(ctx);
 		return { messages: applied.messages };
 	} catch (error) {
 		recordCompressionError(runtime, ctx, error);
-		return undefined;
+		return bypassUncompressed();
 	} finally {
 		runtime.state.processing = false;
 	}
 }
 
+function candidateKey(message: AgentMessage, text: string): string {
+	const source = message as AgentMessage & { toolCallId?: string; toolName?: string };
+	return stableHash(JSON.stringify([source.toolCallId, source.toolName, stableHash(text)]));
+}
+
+function replayCachedCandidates(
+	state: HeadroomRuntimeState, messages: AgentMessage[], payload: CompressionPayload, minMessageChars: number,
+): AgentMessage[] | undefined {
+	if (!state.compressedCandidates?.size) return undefined;
+	const mappings = payload.mappings.map((mapping) => ({
+		...mapping,
+		applyTo: mapping.applyTo && state.compressedCandidates?.has(candidateKey(messages[mapping.sourceIndex], mapping.originalText))
+			? mapping.applyTo : null,
+	}));
+	const compressed = mappings.map((mapping) => {
+		const text = mapping.applyTo && state.compressedCandidates?.get(candidateKey(messages[mapping.sourceIndex], mapping.originalText));
+		return text && mapping.message.role === "tool" ? { ...mapping.message, content: text } : mapping.message;
+	});
+	const applied = applyCompressionResult(messages, mappings, compressed, { minMessageChars });
+	return applied.ok ? applied.messages : undefined;
+}
+
+function recordCachedCandidates(state: HeadroomRuntimeState, payload: CompressionPayload, messages: AgentMessage[]): void {
+	state.compressedCandidates ??= new Map();
+	for (const mapping of payload.mappings) {
+		if (!mapping.applyTo) continue;
+		const applied = convertMessage(messages[mapping.sourceIndex]);
+		if (!applied || applied.role !== "tool") continue;
+		const text = extractOpenAIText(applied);
+		if (text === mapping.originalText) continue;
+		const key = candidateKey(messages[mapping.sourceIndex], mapping.originalText);
+		state.compressedCandidates.set(key, text);
+		if (state.compressedCandidates.size > MAX_SEEN_CANDIDATE_CONTENT_FINGERPRINTS) {
+			state.compressedCandidates.delete(state.compressedCandidates.keys().next().value!);
+		}
+	}
+}
+
 function allCandidateContentSeen(state: HeadroomRuntimeState, payload: CompressionPayload): boolean {
 	const seen = state.seenCandidateContentFingerprints;
 	if (!seen?.size) return false;
@@ -366,18 +424,26 @@ function allCandidateContentSeen(state: HeadroomRuntimeState, payload: Compressi
 	return hashes.length > 0 && hashes.every((hash) => seen.has(hash));
 }
 
+function ignoreSeenCandidateContent(state: HeadroomRuntimeState, payload: CompressionPayload): void {
+	const seen = state.seenCandidateContentFingerprints;
+	if (!seen?.size) return;
+	for (const mapping of payload.mappings) {
+		if (mapping.applyTo && seen.has(stableHash(mapping.originalText))) mapping.applyTo = null;
+	}
+}
+
 function recordSeenCandidateContent(
 	state: HeadroomRuntimeState,
 	payload: CompressionPayload,
-	compressedMessages: CompressionPayload["messages"],
+	appliedMessages: AgentMessage[],
 ): void {
 	state.seenCandidateContentFingerprints ??= new Set();
 	state.seenCandidateContentOrder ??= [];
-	payload.mappings.forEach((mapping, index) => {
+	payload.mappings.forEach((mapping) => {
 		if (!mapping.applyTo) return;
 		addSeenCandidateHash(state, stableHash(mapping.originalText));
-		const compressed = compressedMessages[index];
-		if (compressed) addSeenCandidateHash(state, stableHash(extractOpenAIText(compressed)));
+		const applied = convertMessage(appliedMessages[mapping.sourceIndex]);
+		if (applied) addSeenCandidateHash(state, stableHash(extractOpenAIText(applied)));
 	});
 }
 
@@ -472,7 +538,7 @@ function recordAppliedCompression(stats: HeadroomStats, result: CompressResult,
 function summarizeTelemetry(state: HeadroomRuntimeState): string | null {
 	if (state.stats.last) {
 		const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
-		return `compressed ${state.stats.last.tokensBefore.toLocaleString()} to ${state.stats.last.tokensAfter.toLocaleString()} tokens; saved ${state.stats.last.tokensSaved.toLocaleString()} tokens across ${state.stats.last.appliedMessages} tool results (-${pct}%)`;
+		return `last compression estimated about ${state.stats.last.tokensSaved.toLocaleString()} tokens saved (-${pct}%) across ${state.stats.last.appliedMessages} tool results; local session estimate about ${state.stats.tokensSaved.toLocaleString()} tokens saved`;
 	}
 	if (!state.enabled) return "headroom loaded but disabled for this session";
 	if (state.stats.lastSkipReason) return `compression not applied; last guard skip: ${state.stats.lastSkipReason}`;
@@ -524,7 +590,7 @@ function announceAppliedCompression(
 ): void {
 	if (mode === "quiet" || mode === "silent") return;
 	const pct = Math.round((1 - result.compressionRatio) * 100);
-	const summary = `compressed ${result.tokensBefore.toLocaleString()} → ${result.tokensAfter.toLocaleString()} tokens (-${pct}%, saved ${result.tokensSaved.toLocaleString()}, messages ${appliedMessages})`;
+	const summary = `compressed ${appliedMessages} tool results; estimated ~${result.tokensSaved.toLocaleString()} tokens saved (-${pct}%)`;
 	const line = `noheadroom: ${summary}`;
 	ctx.ui.notify(line, "info");
 	// Note: we no longer use pi.appendEntry or pi.sendMessage here because
@@ -661,12 +727,7 @@ function renderFooterStatus(ctx: ExtensionContext, config: HeadroomConfig, state
 	if (state.proxyStarting) return paint("dim", "⏳ Headroom starting");
 	if (state.proxyOnline === false) return paint("dim", "○ Headroom not running");
 	if (state.proxyOnline === null && !state.stats.last) return paint("dim", "○ Headroom idle");
-	if (!state.stats.last) return paint("success", "✓") + paint("dim", " Headroom");
-
-	const pct = Math.round((1 - state.stats.last.compressionRatio) * 100);
-	return (
-		paint("success", "✓") + paint("dim", ` Headroom -${pct}% (${state.stats.last.tokensSaved.toLocaleString()} saved)`)
-	);
+	return paint("success", "✓") + paint("dim", " Headroom active");
 }
 
 async function showProxyStats(
@@ -706,7 +767,8 @@ function renderStatus(config: HeadroomConfig, state: HeadroomRuntimeState): stri
 		`  Attempts:     ${stats.attempts}`,
 		`  Applied:      ${stats.applied}`,
 		`  Guard skips:  ${stats.guardSkips}`,
-		`  Tokens saved: ${stats.tokensSaved.toLocaleString()}`,
+		`  Estimated tokens saved: ~${stats.tokensSaved.toLocaleString()}`,
+		`  Note: local estimate; proxy /stats does not track Pi extension /v1/compress calls.`,
 	];
 	if (stats.last) {
 		const pct = Math.round((1 - stats.last.compressionRatio) * 100);

package/extensions/proxy-manager.ts

@@ -22,26 +22,32 @@ export async function startPersistentHeadroomProxy(
 			env: {
 				...process.env,
 				HEADROOM_TELEMETRY: process.env.HEADROOM_TELEMETRY || "off",
+				HEADROOM_BEACON: process.env.HEADROOM_BEACON || "off",
 			},
 		});
-		child.unref();
-		return { ok: true };
+		return await new Promise((resolve) => {
+			child.once("error", (error) => resolve({ ok: false, reason: error.message }));
+			child.once("spawn", () => {
+				child.unref();
+				resolve({ ok: true });
+			});
+		});
 	} catch (error) {
 		return { ok: false, reason: error instanceof Error ? error.message : String(error) };
 	}
 }
 
 export function buildProxyArgs(endpoint: ProxyEndpoint): string[] {
-	return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "token", "--no-cache"];
+	return ["proxy", "--host", endpoint.host, "--port", endpoint.port, "--mode", "cache", "--lossless", "--no-cache"];
 }
 
 export function parseLocalEndpoint(baseUrl: string): ProxyEndpoint | undefined {
 	try {
 		const url = new URL(baseUrl);
-		if (!["http:", "https:"].includes(url.protocol)) return undefined;
+		if (url.protocol !== "http:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) return undefined;
 		if (!["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname)) return undefined;
 		const host = url.hostname === "localhost" ? "127.0.0.1" : url.hostname.replace(/^\[(.*)]$/, "$1");
-		const port = url.port || "8787";
+		const port = url.port || "80";
 		return { host, port };
 	} catch {
 		return undefined;

package/extensions/types.ts

@@ -108,5 +108,13 @@ export interface ApplyCompressionOptions {
 }
 
 export type ApplyCompressionResult =
-	| { ok: true; messages: AgentMessage[]; appliedMessages: number }
+	| {
+			ok: true;
+			messages: AgentMessage[];
+			appliedMessages: number;
+			appliedTokensBefore: number;
+			appliedTokensAfter: number;
+			appliedTokensSaved: number;
+			appliedCompressionRatio: number;
+	  }
 	| { ok: false; reason: string };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/noheadroom",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Personal Headroom compression bridge for Pi with Docker-first defaults and Pi tool-name adaptation",
   "main": "dist/index.js",
   "type": "module",