@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/memory/persistent-memory.js

@@ -42,7 +42,7 @@ function mapFactCategoryToMemoryCategory(cat) {
 }
 const DEFAULT_CONFIG = {
     projectMemoryPath: ".codebuddy/CODEBUDDY_MEMORY.md",
-    userMemoryPath: path.join(os.homedir(), ".codebuddy", "memory.md"),
+    get userMemoryPath() { return path.join(os.homedir(), ".codebuddy", "memory.md"); },
     autoCapture: true,
     maxMemories: 100,
     relevanceThreshold: 0.5,
@@ -215,6 +215,10 @@ export class PersistentMemoryManager extends EventEmitter {
     constructor(config = {}) {
         super();
         this.config = { ...DEFAULT_CONFIG, ...config };
+        // Freeze relative paths at construction; later process/session cwd changes
+        // must not redirect a delayed metadata flush to another project.
+        this.config.projectMemoryPath = path.resolve(this.config.projectMemoryPath);
+        this.config.userMemoryPath = path.resolve(this.config.userMemoryPath);
     }
     /**
      * Initialize memory system, loading existing memories.
@@ -446,6 +450,7 @@ export class PersistentMemoryManager extends EventEmitter {
         }
         const previousMemories = cloneMemoryMap(memories);
         let resultKey = normalizedKey;
+        let reconciliation = { status: 'skipped', reason: 'no LLM provider available' };
         try {
             const { FactsMemoryService } = await import('./facts-memory.js');
             const service = new FactsMemoryService();
@@ -485,6 +490,7 @@ export class PersistentMemoryManager extends EventEmitter {
                         tags: mergeMemoryTags(prior?.tags, fact.source, tags)
                     });
                 }
+                await this.guardReconciliation(previousMemories, memories, scope, normalizedKey);
                 if (!memories.has(normalizedKey)) {
                     const newKeys = Array.from(memories.keys()).filter((memoryKey) => !previousMemories.has(memoryKey));
                     const reconciledKey = newKeys[newKeys.length - 1];
@@ -493,6 +499,7 @@ export class PersistentMemoryManager extends EventEmitter {
                     }
                     resultKey = reconciledKey;
                 }
+                reconciliation = { status: 'applied' };
             }
             else {
                 // Fallback to default direct write
@@ -501,6 +508,8 @@ export class PersistentMemoryManager extends EventEmitter {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            reconciliation = { status: 'failed', reason: message };
+            resultKey = normalizedKey;
             logger.warn(`[FactsMemory] Failed to reconcile remember, falling back to default behavior: ${message}`);
             memories.clear();
             for (const [memoryKey, memory] of previousMemories) {
@@ -543,6 +552,7 @@ export class PersistentMemoryManager extends EventEmitter {
             message: status === 'updated'
                 ? `Updated "${resultKey}" in ${scope} memory.`
                 : `Stored "${resultKey}" in ${scope} memory.`,
+            reconciliation,
         };
     }
     async replace(key, value, options = {}) {
@@ -826,6 +836,45 @@ export class PersistentMemoryManager extends EventEmitter {
             ...(m.tags ? { tags: [...m.tags] } : {}),
         }));
     }
+    /** Guard the result, including model renames/omissions, rather than trusting DELETE alone. */
+    async guardReconciliation(previous, next, scope, explicitKey) {
+        const removed = [];
+        const protection = resolveForgettingConfig();
+        for (const [key, memory] of previous) {
+            const replacement = next.get(key);
+            if (isProtectedMemory(memory, protection)) {
+                if (key !== explicitKey || !replacement)
+                    next.set(key, memory);
+                else
+                    next.set(key, { ...replacement, category: memory.category, tags: mergeMemoryTags(memory.tags, undefined, replacement.tags) });
+            }
+            else if (!replacement || replacement.value !== memory.value || replacement.category !== memory.category) {
+                removed.push(memory);
+            }
+        }
+        if (!removed.length)
+            return;
+        const archivePath = this.getArchivePath(scope);
+        const now = new Date();
+        const lines = removed.map(memory => {
+            const tags = memory.tags?.length ? ` [${memory.tags.join(', ')}]` : '';
+            const ageDays = Math.max(0, Math.round((now.getTime() - memory.createdAt.getTime()) / 86_400_000));
+            return `- **${memory.key}** (${memory.category}${tags}, accessed ${memory.accessCount}×, age ${ageDays}d, retention 1.000): ${escapeArchiveValue(memory.value)}`;
+        });
+        // Same recoverable format as forgetting. Durable archive precedes deletion;
+        // failures propagate to the caller's snapshot rollback/direct-write fallback.
+        await withSessionLock(archivePath, async () => {
+            let existing = '';
+            try {
+                existing = await fs.readFile(archivePath, 'utf8');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            await writeFileAtomic(archivePath, `${existing}\n## Forgotten ${now.toISOString()}\n${lines.join('\n')}\n`, { mode: 0o600 });
+        });
+    }
     /**
      * Ebbinghaus forgetting pass (recoverable): memories whose retention decayed
      * below the threshold are appended to a sibling `*.archive.md`, then removed.
@@ -1225,6 +1274,7 @@ export class PersistentMemoryManager extends EventEmitter {
     async autoCapture(message, response) {
         if (!this.config.autoCapture)
             return;
+        const beforeCapture = cloneMemoryMap(this.projectMemories);
         try {
             const { FactsMemoryService } = await import('./facts-memory.js');
             const service = new FactsMemoryService();
@@ -1271,9 +1321,14 @@ export class PersistentMemoryManager extends EventEmitter {
                     tags: mergeMemoryTags(prior?.tags, fact.source, ['auto-captured'])
                 });
             }
+            await this.guardReconciliation(priorProjectMemories, this.projectMemories, 'project');
+            this.assertScopeWithinLimit('project');
             await this.saveMemories("project");
         }
         catch (err) {
+            this.projectMemories.clear();
+            for (const [key, memory] of beforeCapture)
+                this.projectMemories.set(key, memory);
             const reason = err instanceof Error ? err.message : String(err);
             if (err instanceof FactsExtractionError) {
                 logger.warn(`[FactsMemory] Failed to autoCapture facts: ${reason}`);
@@ -1424,40 +1479,32 @@ function unescapeArchiveValue(value) {
         .slice(ARCHIVE_ESCAPED_VALUE_PREFIX.length)
         .replace(/\\(\\|n)/g, (_match, escaped) => escaped === "n" ? "\n" : "\\");
 }
-// Default singleton instance (no bot scope) + per-bot instances.
-let memoryManagerInstance = null;
-const memoryManagerByBot = new Map();
-/**
- * Get the memory manager. With no `botId`, returns the global singleton (default
- * — CLI / desktop / server behavior unchanged). With a `botId` (multi-bot
- * channels), returns a per-bot instance whose memory files live under
- * `~/.codebuddy/bots/<botId>/`, so bots never share each other's `remember` facts.
- */
-export function getMemoryManager(config, botId) {
-    if (!botId) {
-        if (!memoryManagerInstance) {
-            memoryManagerInstance = new PersistentMemoryManager(config);
-        }
-        return memoryManagerInstance;
-    }
-    let inst = memoryManagerByBot.get(botId);
-    if (!inst) {
-        const botDir = path.join(os.homedir(), '.codebuddy', 'bots', botId);
-        inst = new PersistentMemoryManager({
-            ...(config ?? {}),
-            userMemoryPath: path.join(botDir, 'memory.md'),
-            projectMemoryPath: path.join(botDir, 'CODEBUDDY_MEMORY.md'),
+// A project manager is shared by its tools, prompt reader and review queue.
+const memoryManagers = new Map();
+export function getMemoryManager(config, botId, cwd = process.cwd()) {
+    const root = path.resolve(cwd);
+    // Bot memory deliberately remains per-bot (historical channel contract).
+    const key = botId ? `bot:${botId}` : `project:${root}`;
+    let manager = memoryManagers.get(key);
+    if (!manager) {
+        const botDir = botId ? path.join(os.homedir(), '.codebuddy', 'bots', botId) : undefined;
+        manager = new PersistentMemoryManager({
+            projectMemoryPath: path.join(root, '.codebuddy', 'CODEBUDDY_MEMORY.md'),
+            ...config,
+            ...(botDir ? {
+                userMemoryPath: path.join(botDir, 'memory.md'),
+                projectMemoryPath: path.join(botDir, 'CODEBUDDY_MEMORY.md'),
+            } : {}),
         });
-        memoryManagerByBot.set(botId, inst);
+        memoryManagers.set(key, manager);
     }
-    return inst;
+    return manager;
 }
 export function resetMemoryManagerForTests() {
-    memoryManagerInstance = null;
-    memoryManagerByBot.clear();
+    memoryManagers.clear();
 }
-export async function initializeMemory(config) {
-    const manager = getMemoryManager(config);
+export async function initializeMemory(config, cwd) {
+    const manager = getMemoryManager(config, undefined, cwd);
     await manager.initialize();
     return manager;
 }

package/dist/nodes/device-node.js

@@ -10,7 +10,7 @@ import * as os from 'os';
 import * as crypto from 'crypto';
 import { logger } from '../utils/logger.js';
 import { getPlatformCommands } from './platform-commands.js';
-import { readJsonAtomicSync, writeJsonAtomicSync } from '../utils/atomic-write.js';
+import { readDeviceStoreFile, updateDeviceStoreFile } from '../utils/device-store-file.js';
 function validCoordinates(lat, lon) {
     const latitude = typeof lat === 'number'
         ? lat
@@ -74,13 +74,9 @@ export class DeviceNodeManager {
     // ==========================================================================
     loadDevices() {
         try {
-            const data = readJsonAtomicSync(DEVICES_FILE, null, {
-                mode: 0o600,
-                isValid: (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value) &&
-                    value.version === DEVICES_VERSION &&
-                    Array.isArray(value.devices)),
-            });
-            if (data) {
+            // The shared envelope also carries revocations; never restore stale backups.
+            const data = readDeviceStoreFile(DEVICES_FILE);
+            if (data.version === DEVICES_VERSION && Array.isArray(data.devices)) {
                 for (const d of data.devices) {
                     this.devices.set(d.id, d);
                 }
@@ -96,7 +92,7 @@ export class DeviceNodeManager {
                 version: DEVICES_VERSION,
                 devices: Array.from(this.devices.values()),
             };
-            writeJsonAtomicSync(DEVICES_FILE, data, { mode: 0o600 });
+            updateDeviceStoreFile(DEVICES_FILE, envelope => Object.assign(envelope, data));
         }
         catch (err) {
             logger.warn('Failed to save devices', {

package/dist/observability/mobile-supervision-gateway-contract.js

@@ -1,16 +1,29 @@
-import { buildMobileSupervisionSnapshot, evaluateMobileSupervisionAction, } from './mobile-supervision-snapshot.js';
+import { buildMobileSupervisionSnapshot, MOBILE_SUPERVISION_ALLOWED_ACTIONS, MOBILE_SUPERVISION_BLOCKED_ACTIONS, evaluateMobileSupervisionAction, } from './mobile-supervision-snapshot.js';
 export const MOBILE_SUPERVISION_GATEWAY_CONTRACT_SCHEMA_VERSION = 1;
 export async function buildMobileSupervisionGatewayContract(query, options = {}) {
-    const snapshot = await buildMobileSupervisionSnapshot(query, options);
+    // A contract-only preview must not query run/session databases. Besides
+    // unnecessary I/O, loading a host-native SQLite store in Electron can abort
+    // the process before a rejected promise can be caught by the IPC bridge.
+    const snapshot = options.includeSnapshot === false
+        ? undefined
+        : await buildMobileSupervisionSnapshot(query, options);
+    const policy = snapshot ?? {
+        allowedActions: [...MOBILE_SUPERVISION_ALLOWED_ACTIONS],
+        blockedActions: [...MOBILE_SUPERVISION_BLOCKED_ACTIONS],
+        safety: {
+            autoDispatch: false, localApprovalRequired: true, outreachDisabled: true,
+            remoteExecutionDisabled: true, redaction: 'secrets-redacted',
+        },
+    };
     const basePath = normalizeBasePath(options.basePath);
     const auth = buildGatewayAuth();
-    const endpoints = buildGatewayEndpoints(snapshot, basePath, auth);
+    const endpoints = buildGatewayEndpoints(policy, basePath, auth);
     return {
         schemaVersion: MOBILE_SUPERVISION_GATEWAY_CONTRACT_SCHEMA_VERSION,
         generatedAt: new Date().toISOString(),
         mode: 'contract_only',
         basePath,
-        query: snapshot.query,
+        query: snapshot?.query ?? query.trim(),
         auth,
         transport: {
             exposure: 'local_first',
@@ -18,11 +31,11 @@ export async function buildMobileSupervisionGatewayContract(query, options = {})
             remoteExecution: 'disabled',
         },
         endpoints,
-        blockedOperations: snapshot.blockedActions.map(action => ({
+        blockedOperations: policy.blockedActions.map(action => ({
             action,
-            policy: evaluateMobileSupervisionAction(snapshot, action),
+            policy: evaluateMobileSupervisionAction(policy, action),
         })),
-        snapshot: options.includeSnapshot === false ? undefined : snapshot,
+        snapshot,
     };
 }
 export function renderMobileSupervisionGatewayContract(contract) {

package/dist/observability/run-event-writer.d.ts

@@ -0,0 +1,21 @@
+import type { WriteStream } from 'node:fs';
+export interface RunPersistenceStatus {
+    state: 'pending' | 'flushed' | 'failed';
+    received: number;
+    written: number;
+    error?: string;
+}
+/** Tracks stream acknowledgements separately from in-memory observability. */
+export declare class RunEventWriter {
+    private readonly stream;
+    private readonly onFailure;
+    private received;
+    private written;
+    private failure?;
+    constructor(stream: WriteStream, onFailure: (error: Error) => void);
+    private fail;
+    write(line: string): void;
+    status(): RunPersistenceStatus;
+    /** A stream flush, not an fsync guarantee. Rejects on any prior lost event. */
+    flush(): Promise<RunPersistenceStatus>;
+}

package/dist/observability/run-event-writer.js

@@ -0,0 +1,81 @@
+/** Tracks stream acknowledgements separately from in-memory observability. */
+export class RunEventWriter {
+    stream;
+    onFailure;
+    received = 0;
+    written = 0;
+    failure;
+    constructor(stream, onFailure) {
+        this.stream = stream;
+        this.onFailure = onFailure;
+        stream.on('error', error => this.fail(error));
+    }
+    fail(error) {
+        if (this.failure)
+            return;
+        this.failure = error;
+        this.onFailure(error);
+    }
+    write(line) {
+        this.received++;
+        if (this.failure)
+            return;
+        if (this.stream.writableLength + Buffer.byteLength(line) > 1024 * 1024) {
+            this.fail(new Error('Run event queue exceeded 1 MiB; journal is incomplete'));
+            return;
+        }
+        try {
+            this.stream.write(line, error => {
+                if (error)
+                    this.fail(error);
+                else
+                    this.written++;
+            });
+        }
+        catch (error) {
+            this.fail(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    status() {
+        return {
+            state: this.failure ? 'failed' : this.received === this.written ? 'flushed' : 'pending',
+            received: this.received,
+            written: this.written,
+            ...(this.failure ? { error: this.failure.message } : {}),
+        };
+    }
+    /** A stream flush, not an fsync guarantee. Rejects on any prior lost event. */
+    async flush() {
+        if (this.failure)
+            throw this.failure;
+        if (!this.stream.writableFinished) {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    this.stream.removeListener('error', failed);
+                    this.stream.removeListener('finish', finished);
+                    this.stream.removeListener('close', closed);
+                };
+                const failed = (error) => { cleanup(); reject(error); };
+                const finished = () => { cleanup(); resolve(); };
+                const closed = () => {
+                    if (this.stream.writableFinished)
+                        finished();
+                    else
+                        failed(new Error('Run event stream closed before flush'));
+                };
+                this.stream.once('error', failed);
+                this.stream.once('close', closed);
+                if (this.stream.destroyed)
+                    closed();
+                else if (this.stream.writableEnded)
+                    this.stream.once('finish', finished);
+                else
+                    this.stream.write('', error => error ? failed(error) : finished());
+            }).catch(error => { this.fail(error); throw error; });
+        }
+        if (this.failure)
+            throw this.failure;
+        return this.status();
+    }
+}
+//# sourceMappingURL=run-event-writer.js.map

package/dist/observability/run-store.d.ts

@@ -9,6 +9,7 @@
  * Written in append mode for performance — no full-file parsing per event.
  * Automatic pruning keeps the 30 most recent runs.
  */
+import { type RunPersistenceStatus } from './run-event-writer.js';
 export type RunEventType = 'run_start' | 'run_end' | 'step_start' | 'step_end' | 'tool_call' | 'tool_result' | 'patch_created' | 'patch_applied' | 'decision' | 'error' | 'metric' | 'lesson_added' | 'lesson_candidate_proposed' | 'skill_selected' | 'context_snapshot' | 'pause_suggested';
 export interface RunEvent {
     ts: number;
@@ -57,6 +58,7 @@ export interface RunSummary {
     metadata?: RunMetadata;
 }
 export interface RunRecord {
+    persistence?: RunPersistenceStatus;
     summary: RunSummary;
     metrics: Partial<RunMetrics>;
     artifacts: string[];
@@ -160,6 +162,7 @@ export declare class RunStore {
     private runsDir;
     /** File handles for active run event streams */
     private handles;
+    private eventWriters;
     /** Immediate in-process view of events, avoiding read-after-write stream races. */
     private eventBuffers;
     /** In-memory event counts per run */
@@ -205,6 +208,8 @@ export declare class RunStore {
     /**
      * Emit an event for a run. Thread-safe: writes are serialized by the writable stream.
      */
+    getPersistenceStatus(runId: string): RunPersistenceStatus | undefined;
+    flushRun(runId: string): Promise<RunPersistenceStatus>;
     emit(runId: string, event: Omit<RunEvent, 'ts' | 'runId'>): void;
     /**
      * End a run and flush the event stream.

package/dist/observability/run-store.js

@@ -9,6 +9,7 @@
  * Written in append mode for performance — no full-file parsing per event.
  * Automatic pruning keeps the 30 most recent runs.
  */
+import { RunEventWriter } from './run-event-writer.js';
 import fs from 'fs';
 import path from 'path';
 import os from 'os';
@@ -35,6 +36,7 @@ export class RunStore {
     runsDir;
     /** File handles for active run event streams */
     handles = new Map();
+    eventWriters = new Map();
     /** Immediate in-process view of events, avoiding read-after-write stream races. */
     eventBuffers = new Map();
     /** In-memory event counts per run */
@@ -129,12 +131,9 @@ export class RunStore {
         const eventsPath = path.join(runDir, 'events.jsonl');
         fs.writeFileSync(eventsPath, '', { flag: 'a' }); // ensure file exists
         const ws = fs.createWriteStream(eventsPath, { flags: 'a', encoding: 'utf-8' });
-        ws.on('error', (err) => {
-            logger.debug('RunStore: event stream error', {
-                runId,
-                err: err instanceof Error ? err.message : String(err),
-            });
-        });
+        this.eventWriters.set(runId, new RunEventWriter(ws, error => {
+            logger.warn('RunStore: journal persistence failed', { runId, error: error.message });
+        }));
         this.handles.set(runId, ws);
         // Emit run_start event
         this.emit(runId, { type: 'run_start', data: { objective, metadata } });
@@ -198,6 +197,15 @@ export class RunStore {
     /**
      * Emit an event for a run. Thread-safe: writes are serialized by the writable stream.
      */
+    getPersistenceStatus(runId) {
+        return this.eventWriters.get(runId)?.status();
+    }
+    async flushRun(runId) {
+        const writer = this.eventWriters.get(runId);
+        if (!writer)
+            throw new Error(`No active journal writer for run ${runId}`);
+        return writer.flush();
+    }
     emit(runId, event) {
         const ws = this.handles.get(runId);
         if (!ws)
@@ -211,12 +219,7 @@ export class RunStore {
         if (buffer) {
             buffer.push(fullEvent);
         }
-        try {
-            ws.write(JSON.stringify(fullEvent) + '\n');
-        }
-        catch (err) {
-            logger.debug('RunStore: failed to write event', { runId, err });
-        }
+        this.eventWriters.get(runId)?.write(JSON.stringify(fullEvent) + '\n');
         // Update in-memory count
         const count = (this.eventCounts.get(runId) || 0) + 1;
         this.eventCounts.set(runId, count);
@@ -396,7 +399,8 @@ export class RunStore {
         catch {
             // Ignore
         }
-        return { summary, metrics, artifacts };
+        const persistence = this.getPersistenceStatus(runId);
+        return { summary, metrics, artifacts, ...(persistence ? { persistence } : {}) };
     }
     /**
      * List runs, most recent first.
@@ -1055,6 +1059,7 @@ export class RunStore {
             if (ws) {
                 ws.destroy();
                 this.handles.delete(s.runId);
+                this.eventWriters.delete(s.runId);
             }
             // Remove directory after a short delay to let the stream fully close
             setTimeout(() => {

package/dist/observability/run-trajectory.js

@@ -5,7 +5,7 @@
  * The CLI is only a presenter. No new telemetry is written.
  */
 import os from 'node:os';
-import { resolveToolEffect } from '../tools/metadata.js';
+import { resolveToolEffect } from '../tools/tool-effect.js';
 export const RUN_TRAJECTORY_SCHEMA_VERSION = 1;
 export const RUN_TRAJECTORY_KIND = 'run_trajectory';
 export function unlogged(reason) {

package/dist/optimization/prompt-cache.d.ts

@@ -1,8 +1,8 @@
 /**
  * Prompt Caching Module
  *
- * Implements prompt caching for LLM API calls to reduce costs and latency.
- * Research shows up to 90% cost reduction and 80% latency improvement.
+ * Tracks local prompt repetition and exact component changes. Cache hits and
+ * savings here are heuristics, not measurements of a provider's prompt cache.
  *
  * References:
  * - OpenAI Prompt Caching: https://platform.openai.com/docs/guides/prompt-caching
@@ -31,6 +31,19 @@ export interface CacheStats {
     estimatedCostSaved: number;
     entries: number;
 }
+/** Consecutive raw observations within this manager, not provider cache usage. */
+export interface PrefixStabilityStats {
+    system: {
+        observations: number;
+        unchanged: number;
+        changes: number;
+    };
+    tools: {
+        observations: number;
+        unchanged: number;
+        changes: number;
+    };
+}
 /**
  * Cache configuration
  */
@@ -58,11 +71,13 @@ export declare class PromptCacheManager extends EventEmitter {
     private systemPromptHash;
     private toolsHash;
     private contextHashes;
+    private prefixStats;
     constructor(config?: Partial<CacheConfig>);
     /**
      * Generate hash for content
      */
     private hash;
+    private observePrefix;
     /**
      * Estimate token count (rough approximation)
      */
@@ -103,6 +118,8 @@ export declare class PromptCacheManager extends EventEmitter {
      * Get cache statistics
      */
     getStats(): CacheStats;
+    /** Includes short components below the cache threshold; stores no prompt text. */
+    getPrefixStats(): PrefixStabilityStats;
     /**
      * Format stats for display
      */

package/dist/optimization/prompt-cache.js

@@ -1,8 +1,8 @@
 /**
  * Prompt Caching Module
  *
- * Implements prompt caching for LLM API calls to reduce costs and latency.
- * Research shows up to 90% cost reduction and 80% latency improvement.
+ * Tracks local prompt repetition and exact component changes. Cache hits and
+ * savings here are heuristics, not measurements of a provider's prompt cache.
  *
  * References:
  * - OpenAI Prompt Caching: https://platform.openai.com/docs/guides/prompt-caching
@@ -42,6 +42,11 @@ export class PromptCacheManager extends EventEmitter {
     systemPromptHash = null;
     toolsHash = null;
     contextHashes = new Map();
+    // Fixed-size diagnostics: retain only the previous component hashes and counts.
+    prefixStats = {
+        system: { observations: 0, unchanged: 0, changes: 0 },
+        tools: { observations: 0, unchanged: 0, changes: 0 },
+    };
     constructor(config = {}) {
         super();
         this.config = { ...DEFAULT_CACHE_CONFIG, ...config };
@@ -52,6 +57,23 @@ export class PromptCacheManager extends EventEmitter {
     hash(content) {
         return createHash("sha256").update(content).digest("hex").slice(0, 16);
     }
+    observePrefix(type, hash) {
+        if (!this.config.enabled)
+            return;
+        const previous = type === 'system' ? this.systemPromptHash : this.toolsHash;
+        const stats = this.prefixStats[type];
+        stats.observations++;
+        if (previous !== null) {
+            if (previous === hash)
+                stats.unchanged++;
+            else
+                stats.changes++;
+        }
+        if (type === 'system')
+            this.systemPromptHash = hash;
+        else
+            this.toolsHash = hash;
+    }
     /**
      * Estimate token count (rough approximation)
      */
@@ -96,9 +118,9 @@ export class PromptCacheManager extends EventEmitter {
     cacheSystemPrompt(prompt) {
         const hash = this.hash(prompt);
         const tokens = this.estimateTokens(prompt);
+        this.observePrefix('system', hash);
         if (tokens >= this.config.minTokensToCache) {
             this.addEntry(hash, tokens, "system");
-            this.systemPromptHash = hash;
         }
         return hash;
     }
@@ -109,9 +131,9 @@ export class PromptCacheManager extends EventEmitter {
         const content = JSON.stringify(tools);
         const hash = this.hash(content);
         const tokens = this.estimateTokens(content);
+        this.observePrefix('tools', hash);
         if (tokens >= this.config.minTokensToCache) {
             this.addEntry(hash, tokens, "tools");
-            this.toolsHash = hash;
         }
         return hash;
     }
@@ -176,6 +198,13 @@ export class PromptCacheManager extends EventEmitter {
     getStats() {
         return { ...this.stats };
     }
+    /** Includes short components below the cache threshold; stores no prompt text. */
+    getPrefixStats() {
+        return {
+            system: { ...this.prefixStats.system },
+            tools: { ...this.prefixStats.tools },
+        };
+    }
     /**
      * Format stats for display
      */
@@ -184,8 +213,10 @@ export class PromptCacheManager extends EventEmitter {
             "📦 Prompt Cache Statistics",
             `├─ Entries: ${this.stats.entries}`,
             `├─ Hit Rate: ${(this.stats.hitRate * 100).toFixed(1)}%`,
-            `├─ Tokens Saved: ${this.stats.totalTokensSaved.toLocaleString()}`,
-            `└─ Est. Cost Saved: $${this.stats.estimatedCostSaved.toFixed(4)}`,
+            `├─ Est. Reused Tokens: ${this.stats.totalTokensSaved.toLocaleString()}`,
+            `├─ Est. Cost Saved (heuristic): $${this.stats.estimatedCostSaved.toFixed(4)}`,
+            `└─ Prefix Changes (local): system ${this.prefixStats.system.changes}, tools ${this.prefixStats.tools.changes}`,
+            'Local repetition estimates; provider cache usage is not measured.',
         ];
         return lines.join("\n");
     }
@@ -197,6 +228,10 @@ export class PromptCacheManager extends EventEmitter {
         this.systemPromptHash = null;
         this.toolsHash = null;
         this.contextHashes.clear();
+        this.prefixStats = {
+            system: { observations: 0, unchanged: 0, changes: 0 },
+            tools: { observations: 0, unchanged: 0, changes: 0 },
+        };
         logger.debug("Prompt cache cleared");
     }
     /**