@google/gemini-cli-core 0.44.0 → 0.45.0-preview.0

package/dist/src/context/config/types.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { ContextProcessor, AsyncContextProcessor } from '../pipeline.js';
-export type PipelineTrigger = 'new_message' | 'retained_exceeded' | 'gc_backstop' | 'nodes_added' | 'nodes_aged_out' | {
+export type PipelineTrigger = 'new_message' | 'retained_exceeded' | 'normalized_exceeded' | 'gc_backstop' | 'nodes_added' | 'nodes_aged_out' | {
     type: 'timer';
     intervalMs: number;
 };
@@ -20,6 +20,7 @@ export interface AsyncPipelineDef {
 }
 export interface ContextBudget {
     retainedTokens: number;
+    normalizedTokens?: number;
     maxTokens: number;
     /**
      * Only trigger background consolidation (snapshots) when at least this many
@@ -33,6 +34,12 @@ export interface ContextBudget {
 export interface ContextManagementConfig {
     /** Defines the token ceilings and limits for the pipeline. */
     budget: ContextBudget;
+    /**
+     * Strategy for the GC backstop when maxTokens is exceeded.
+     * 'bulk' (default): Processes all nodes that have aged out of retainedTokens.
+     * 'incremental': Processes only the oldest nodes necessary to get back under maxTokens.
+     */
+    gcStrategy?: 'bulk' | 'incremental';
     /**
      * Dynamic hyperparameter overrides for individual ContextProcessors and AsyncProcessors.
      * Keys are named identifiers (e.g. "gentleTruncation").

package/dist/src/context/contextManager.d.ts

@@ -23,33 +23,11 @@ export declare class ContextManager {
     private readonly orchestrator;
     private readonly evaluatedNodeIds;
     private lastTriggeredDeficit;
+    private lastTriggeredNormalizeDeficit;
     private lastRenderCache?;
     private hasPerformedHotStart;
     constructor(sidecar: ContextProfile, env: ContextEnvironment, tracer: ContextTracer, orchestrator: PipelineOrchestrator, chatHistory: AgentChatHistory, advancedTokenCalculator: AdvancedTokenCalculator, headerProvider?: (() => Promise<Content | undefined>) | undefined);
-    /**
-     * Returns a promise that resolves when all currently executing async pipelines have finished.
-     */
-    waitForPipelines(): Promise<void>;
-    /**
-     * Safely stops background async pipelines and clears event listeners.
-     */
-    shutdown(): void;
-    /**
-     * Evaluates if the current working buffer exceeds configured budget thresholds,
-     * firing consolidation events if necessary.
-     */
-    private evaluateTriggers;
-    private getProtectedNodeIds;
-    getPristineGraph(): readonly ConcreteNode[];
-    getNodes(): readonly ConcreteNode[];
-    /**
-     * Generates a virtual view of the pristine graph, substituting in variants
-     * up to the configured token budget.
-     */
-    renderHistory(pendingRequest?: {
-        id: string;
-        content: Content;
-    }, activeTaskIds?: Set<string>, abortSignal?: AbortSignal): Promise<{
+    renderHistory(pendingRequest?: HistoryTurn, activeTaskIds?: Set<string>, abortSignal?: AbortSignal): Promise<{
         history: HistoryTurn[];
         apiHistory: Content[];
         pendingApiHistory: Content[];
@@ -57,6 +35,12 @@ export declare class ContextManager {
         baseUnits: number;
         processedNodes: readonly ConcreteNode[];
     }>;
-    private performHotStartCalibration;
+    waitForPipelines(): Promise<void>;
+    shutdown(): void;
+    getNodes(): readonly ConcreteNode[];
     getEnvironment(): ContextEnvironment;
+    getPristineGraph(): readonly ConcreteNode[];
+    private evaluateTriggers;
+    private getProtectedNodeIds;
+    private performHotStartCalibration;
 }

package/dist/src/context/contextManager.incremental.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export {};

package/dist/src/context/contextManager.incremental.test.js

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { ContextManager } from './contextManager.js';
+import { createMockEnvironment, createDummyNode, } from './testing/contextTestUtils.js';
+import { NodeType } from './graph/types.js';
+describe('ContextManager - Multi-stage and Incremental GC', () => {
+    let mockEnv;
+    let mockOrchestrator;
+    let mockChatHistory;
+    let mockAdvancedTokenCalculator;
+    beforeEach(() => {
+        mockEnv = createMockEnvironment();
+        mockOrchestrator = {
+            setNodeProvider: vi.fn(),
+            waitForPipelines: vi.fn().mockResolvedValue(undefined),
+            executeTriggerSync: vi
+                .fn()
+                .mockImplementation(async (trigger, buffer) => buffer),
+            executeIngestionPipeline: vi
+                .fn()
+                .mockImplementation(async (nodes) => nodes),
+            shutdown: vi.fn(),
+        };
+        mockChatHistory = {
+            all: vi.fn().mockReturnValue([]),
+            getHistory: vi.fn().mockReturnValue([]),
+            get: vi.fn().mockReturnValue([]),
+            subscribe: vi.fn(),
+        };
+        mockAdvancedTokenCalculator = {
+            getRawBaseUnits: vi.fn().mockReturnValue(0),
+            getRawBaseUnitsForContent: vi.fn().mockReturnValue(0),
+            calculateTokensAndBaseUnits: vi.fn(),
+        };
+    });
+    const setupManager = (config) => {
+        const sidecar = {
+            name: 'test',
+            config,
+            buildPipelines: () => [],
+            buildAsyncPipelines: () => [],
+        };
+        return new ContextManager(sidecar, mockEnv, mockEnv.tracer, mockOrchestrator, mockChatHistory, mockAdvancedTokenCalculator);
+    };
+    it('should emit NormalizeNeeded when normalizedTokens budget is exceeded', async () => {
+        const manager = setupManager({
+            budget: {
+                retainedTokens: 100,
+                normalizedTokens: 150,
+                maxTokens: 300,
+            },
+        });
+        const normalizeSpy = vi.fn();
+        mockEnv.eventBus.onNormalizeNeeded(normalizeSpy);
+        const consolidationSpy = vi.fn();
+        mockEnv.eventBus.onConsolidationNeeded(consolidationSpy);
+        // Mock token calculator for evaluateTriggers
+        mockEnv.tokenCalculator.calculateConcreteListTokens = vi
+            .fn()
+            .mockImplementation((nodes) => nodes.reduce((sum, n) => 
+        // Look for the mock tokens we attached to the dummy node
+        sum + (n._mockTokens || 0), 0));
+        const createNodeWithTokens = (id, type, tokens) => {
+            const node = createDummyNode(id, type);
+            // @ts-expect-error - attaching mock tokens for test
+            node._mockTokens = tokens;
+            return node;
+        };
+        // Create 4 nodes, each 80 tokens. Total = 320 tokens.
+        // Node 1 (oldest): prior=240. 240 > 150 -> Normalization (Archiving trigger)
+        // Node 2: prior=160. 160 > 150 -> Normalization
+        // Node 3: prior=80. 80 <= 100 -> Retained
+        // Node 4 (newest): prior=0. 0 <= 100 -> Retained
+        const nodes = [
+            createNodeWithTokens('ep1', NodeType.USER_PROMPT, 80),
+            createNodeWithTokens('ep2', NodeType.AGENT_THOUGHT, 80),
+            createNodeWithTokens('ep3', NodeType.TOOL_EXECUTION, 80),
+            createNodeWithTokens('ep4', NodeType.TOOL_EXECUTION, 80),
+        ];
+        // @ts-expect-error - access private method for testing
+        manager.buffer = { nodes };
+        // Trigger evaluation manually with a dummy "new node" to bypass the empty check
+        // @ts-expect-error - access private method for testing
+        await manager.evaluateTriggers(nodes, new Set([nodes[3].id]), new Set());
+        // Nodes 3 and 4 are retained.
+        // Node 2 and Node 1 both fall out of normalizedTokens (160 > 150, 240 > 150).
+        // Therefore they should trigger NormalizeNeeded. They should NOT trigger ConsolidationNeeded
+        // because they exceeded normalized budget, so they skip the retained fallback.
+        expect(consolidationSpy).not.toHaveBeenCalled();
+        expect(normalizeSpy).toHaveBeenCalledOnce();
+        const normalizeEvent = normalizeSpy.mock.calls[0][0];
+        expect(normalizeEvent.targetNodeIds.has(nodes[0].id)).toBe(true);
+        expect(normalizeEvent.targetNodeIds.has(nodes[1].id)).toBe(true);
+        expect(normalizeEvent.targetNodeIds.has(nodes[2].id)).toBe(false);
+    });
+});
+//# sourceMappingURL=contextManager.incremental.test.js.map

package/dist/src/context/contextManager.incremental.test.js.map

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

package/dist/src/context/contextManager.js

@@ -24,6 +24,7 @@ export class ContextManager {
     evaluatedNodeIds = new Set();
     // Hysteresis tracking to prevent utility call churn
     lastTriggeredDeficit = 0;
+    lastTriggeredNormalizeDeficit = 0;
     // Cache for Anomaly 3 (Redundant Renders)
     lastRenderCache;
     hasPerformedHotStart = false;
@@ -36,121 +37,22 @@ export class ContextManager {
         this.headerProvider = headerProvider;
         this.eventBus = env.eventBus;
         this.orchestrator = orchestrator;
-        // Provide the orchestrator with a way to fetch the latest nodes from the live buffer
+        // Direct synchronization: ContextManager is the "Pull Master"
+        // and tells the orchestrator what to do.
         this.orchestrator.setNodeProvider(() => this.buffer.nodes);
         this.eventBus.onProcessorResult((event) => {
             // Defensive: Verify all targets are still present in the buffer.
-            const currentIds = new Set(this.buffer.nodes.map((n) => n.id));
-            const allTargetsPresent = event.targets.every((t) => currentIds.has(t.id));
-            if (!allTargetsPresent) {
-                debugLogger.log(`[ContextManager] Dropping stale processor result from ${event.processorId}. One or more targets were already removed.`);
+            const bufferIds = new Set(this.buffer.nodes.map((n) => n.id));
+            if (!event.targets.every((t) => bufferIds.has(t.id))) {
+                debugLogger.warn(`[ContextManager] Dropping processor result from ${event.processorId}: targets no longer in buffer.`);
                 return;
             }
             this.buffer = this.buffer.applyProcessorResult(event.processorId, event.targets, event.returnedNodes);
         });
     }
-    /**
-     * Returns a promise that resolves when all currently executing async pipelines have finished.
-     */
-    async waitForPipelines() {
-        return this.orchestrator.waitForPipelines();
-    }
-    /**
-     * Safely stops background async pipelines and clears event listeners.
-     */
-    shutdown() {
-        this.orchestrator.shutdown();
-    }
-    /**
-     * Evaluates if the current working buffer exceeds configured budget thresholds,
-     * firing consolidation events if necessary.
-     */
-    async evaluateTriggers(newNodes) {
-        if (!this.sidecar.config.budget)
-            return;
-        if (newNodes.size > 0) {
-            await this.orchestrator.executeTriggerSync('new_message', this.buffer.nodes, newNodes);
-        }
-        const currentTokens = this.env.tokenCalculator.calculateConcreteListTokens(this.buffer.nodes);
-        if (currentTokens > this.sidecar.config.budget.retainedTokens) {
-            const agedOutNodes = new Set();
-            let rollingTokens = 0;
-            // Identify nodes that must NEVER be truncated
-            const protectedIds = this.getProtectedNodeIds(this.buffer.nodes);
-            // Walk backwards finding nodes that fall out of the retained budget
-            for (let i = this.buffer.nodes.length - 1; i >= 0; i--) {
-                const node = this.buffer.nodes[i];
-                const priorTokens = rollingTokens;
-                rollingTokens += this.env.tokenCalculator.calculateConcreteListTokens([
-                    node,
-                ]);
-                if (priorTokens > this.sidecar.config.budget.retainedTokens) {
-                    if (!protectedIds.has(node.id)) {
-                        agedOutNodes.add(node.id);
-                    }
-                }
-            }
-            if (agedOutNodes.size > 0) {
-                const targetDeficit = currentTokens - this.sidecar.config.budget.retainedTokens;
-                if (targetDeficit < this.lastTriggeredDeficit) {
-                    this.lastTriggeredDeficit = targetDeficit;
-                }
-                const threshold = this.sidecar.config.budget.coalescingThresholdTokens || 0;
-                const growthSinceLast = targetDeficit - this.lastTriggeredDeficit;
-                if (targetDeficit >= threshold &&
-                    (growthSinceLast >= threshold || this.lastTriggeredDeficit === 0)) {
-                    this.lastTriggeredDeficit = targetDeficit;
-                    this.env.tokenCalculator.garbageCollectCache(new Set(this.buffer.nodes.map((n) => n.id)));
-                    // Trigger synchronous consolidation for budget deficit
-                    await this.orchestrator.executeTriggerSync('nodes_aged_out', this.buffer.nodes, agedOutNodes, new Set(protectedIds.keys()));
-                }
-            }
-            else {
-                this.lastTriggeredDeficit = 0;
-            }
-        }
-    }
-    getProtectedNodeIds(nodes, extraProtectedIds = new Set()) {
-        const protectionMap = new Map();
-        if (nodes.length === 0)
-            return protectionMap;
-        const lastNode = nodes[nodes.length - 1];
-        const lastTurnId = lastNode.turnId;
-        const envTurnId = `turn_${deriveStableId(['environment-context'])}`;
-        for (const node of nodes) {
-            if (node.turnId === lastTurnId) {
-                protectionMap.set(node.id, 'recent_turn');
-            }
-            else if (node.turnId === envTurnId) {
-                protectionMap.set(node.id, 'environment_context');
-            }
-        }
-        for (const id of extraProtectedIds) {
-            protectionMap.set(id, 'external_active_task');
-        }
-        return protectionMap;
-    }
-    getPristineGraph() {
-        const pristineSet = new Map();
-        for (const node of this.buffer.nodes) {
-            const roots = this.buffer.getPristineNodes(node.id);
-            for (const root of roots) {
-                pristineSet.set(root.id, root);
-            }
-        }
-        return Array.from(pristineSet.values()).sort((a, b) => a.timestamp - b.timestamp);
-    }
-    getNodes() {
-        return [...this.buffer.nodes];
-    }
-    /**
-     * Generates a virtual view of the pristine graph, substituting in variants
-     * up to the configured token budget.
-     */
     async renderHistory(pendingRequest, activeTaskIds = new Set(), abortSignal) {
         this.tracer.logEvent('ContextManager', 'Starting rendering of LLM context');
         // 1. Explicit Sync with the durable history.
-        // This replaces the background HistoryObserver.
         const currentHistory = this.chatHistory.get();
         const pristineNodes = this.env.graphMapper.sync(currentHistory);
         this.buffer = this.buffer.syncPristineHistory(pristineNodes);
@@ -165,12 +67,12 @@ export class ContextManager {
         // 2. Preview the pending request.
         let previewNodes = [];
         if (pendingRequest) {
-            previewNodes = this.env.graphMapper.sync([pendingRequest]);
-            const previewNodeIds = new Set(previewNodes.map((n) => n.id));
-            previewNodes = await this.orchestrator.executeTriggerSync('new_message', previewNodes, previewNodeIds);
+            const syncedNodes = this.env.graphMapper.sync([pendingRequest]);
+            const previewNodeIds = new Set(syncedNodes.map((n) => n.id));
+            const previewBuffer = ContextWorkingBufferImpl.initialize(syncedNodes);
+            const processedPreviewBuffer = await this.orchestrator.executeTriggerSync('new_message', previewBuffer, previewNodeIds);
+            previewNodes = processedPreviewBuffer.nodes;
         }
-        // 3. Trigger evaluation (Sync budget management).
-        await this.evaluateTriggers(newPrimalNodes);
         // --- Hot Start Calibration ---
         const hotStartPromise = (async () => {
             if (!this.hasPerformedHotStart) {
@@ -181,23 +83,30 @@ export class ContextManager {
                 }
             }
         })();
+        // 3. Synchronous Pressure Barrier
         await Promise.all([this.orchestrator.waitForPipelines(), hotStartPromise]);
         let nodes = this.buffer.nodes;
         const previewNodeIds = new Set();
         if (previewNodes.length > 0) {
-            for (const n of previewNodes) {
-                previewNodeIds.add(n.id);
-            }
             nodes = [...nodes, ...previewNodes];
+            for (const node of previewNodes) {
+                previewNodeIds.add(node.id);
+            }
         }
+        // 4. Trigger Management (GC/Distillation/Normalization)
+        await this.evaluateTriggers(nodes, newPrimalNodes, activeTaskIds);
+        // Re-fetch nodes from buffer (master) and combine with ephemeral previews
+        nodes = [...this.buffer.nodes, ...previewNodes];
+        // 5. Final Render
         const header = this.headerProvider
             ? await this.headerProvider()
             : undefined;
-        const graphHash = nodes.map((n) => n.id).join('|');
-        const headerHash = header ? JSON.stringify(header.parts) : 'no-header';
-        const totalHash = `${graphHash}::${headerHash}`;
-        if (this.lastRenderCache?.nodesHash === totalHash) {
-            debugLogger.log('[ContextManager] Render cache hit. Skipping redundant render.');
+        const nodesHash = deriveStableId([
+            ...nodes.map((n) => n.id),
+            header ? JSON.stringify(header.parts) : 'no-header',
+        ]);
+        if (this.lastRenderCache?.nodesHash === nodesHash) {
+            this.tracer.logEvent('ContextManager', 'Render Cache Hit', { nodesHash });
             return this.lastRenderCache.result;
         }
         const protectionReasons = this.getProtectedNodeIds(nodes, activeTaskIds);
@@ -208,45 +117,184 @@ export class ContextManager {
         });
         const { history: renderedHistory, pendingHistory, didApplyManagement, baseUnits, processedNodes, } = renderResult;
         if (didApplyManagement) {
-            this.buffer = this.buffer.applyProcessorResult('sync_backstop', this.buffer.nodes, processedNodes.filter((n) => !previewNodeIds.has(n.id)));
+            // Commit the GC backstop results back to the master buffer.
+            // We must be careful to only apply results to the nodes that belong to the master buffer.
+            const masterIdsInResult = new Set(this.buffer.nodes.map((n) => n.id));
+            const processedMasterNodes = processedNodes.filter((n) => !previewNodeIds.has(n.id) || masterIdsInResult.has(n.id));
+            this.buffer = this.buffer.applyProcessorResult('sync_backstop', this.buffer.nodes, processedMasterNodes);
         }
+        // Structural validation
         checkContextInvariants(this.buffer.nodes, 'RenderHistory');
-        this.tracer.logEvent('ContextManager', 'Finished rendering');
-        const allHistory = [...renderedHistory, ...pendingHistory];
-        const hardenedAllHistory = hardenHistory(allHistory, {
+        const fullHistoryToHarden = [...renderedHistory, ...pendingHistory];
+        const hardenedFullHistory = hardenHistory(fullHistoryToHarden, {
             sentinels: this.sidecar.sentinels,
         });
-        const firstPendingId = pendingHistory[0]?.id;
-        let splitIndex = renderedHistory.length;
-        if (firstPendingId) {
-            const foundIndex = hardenedAllHistory.findIndex((h) => h.id === firstPendingId);
-            if (foundIndex !== -1) {
-                splitIndex = foundIndex;
+        const envContextId = deriveStableId(['environment-context']);
+        const pendingIds = new Set(pendingHistory.map((t) => t.id));
+        const resultHistory = [];
+        const resultPending = [];
+        let foundPending = false;
+        for (const turn of hardenedFullHistory) {
+            if (!foundPending &&
+                (pendingIds.has(turn.id) ||
+                    (turn.id.startsWith('turn_') &&
+                        pendingIds.has(turn.id.substring(5)))) &&
+                turn.id !== envContextId &&
+                turn.id !== `turn_${envContextId}`) {
+                foundPending = true;
+            }
+            if (foundPending) {
+                resultPending.push(turn);
+            }
+            else {
+                resultHistory.push(turn);
             }
-        }
-        const apiHistory = hardenedAllHistory
-            .slice(0, splitIndex)
-            .map((h) => h.content);
-        const pendingApiHistory = hardenedAllHistory
-            .slice(splitIndex)
-            .map((h) => h.content);
-        if (header) {
-            apiHistory.unshift(header);
         }
         const result = {
             history: renderedHistory,
-            apiHistory,
-            pendingApiHistory,
+            apiHistory: resultHistory.map((h) => h.content),
+            pendingApiHistory: resultPending.map((h) => h.content),
             didApplyManagement,
             baseUnits,
             processedNodes,
         };
-        this.lastRenderCache = {
-            nodesHash: totalHash,
-            result,
-        };
+        if (header) {
+            result.apiHistory.unshift(header);
+        }
+        this.lastRenderCache = { nodesHash, result };
+        this.tracer.logEvent('ContextManager', 'Rendering Complete', {
+            historySize: renderedHistory.length,
+            pendingSize: pendingHistory.length,
+            didApplyManagement,
+        });
         return result;
     }
+    async waitForPipelines() {
+        await this.orchestrator.waitForPipelines();
+    }
+    shutdown() {
+        this.orchestrator.shutdown();
+    }
+    getNodes() {
+        return this.buffer.nodes;
+    }
+    getEnvironment() {
+        return this.env;
+    }
+    getPristineGraph() {
+        const pristineSet = new Map();
+        for (const node of this.buffer.nodes) {
+            const roots = this.buffer.getPristineNodes(node.id);
+            for (const root of roots) {
+                pristineSet.set(root.id, root);
+            }
+        }
+        return Array.from(pristineSet.values()).sort((a, b) => a.timestamp - b.timestamp);
+    }
+    async evaluateTriggers(nodes, newPrimalNodes, activeTaskIds) {
+        if (newPrimalNodes.size > 0) {
+            this.buffer = await this.orchestrator.executeTriggerSync('nodes_added', this.buffer, newPrimalNodes);
+        }
+        // Identify ephemeral preview nodes that are NOT in the master buffer.
+        const bufferIds = new Set(this.buffer.nodes.map((n) => n.id));
+        const previewNodes = nodes.filter((n) => !bufferIds.has(n.id));
+        const currentNodes = [...this.buffer.nodes, ...previewNodes];
+        const currentTokens = this.env.tokenCalculator.calculateConcreteListTokens(currentNodes);
+        if (currentTokens > this.sidecar.config.budget.retainedTokens) {
+            const agedOutRetainedNodes = new Set();
+            const agedOutNormalizedNodes = new Set();
+            const protectionMap = this.getProtectedNodeIds(currentNodes, activeTaskIds);
+            const protectedIds = new Set(protectionMap.keys());
+            // Also pin Turn 0 (Environment Context)
+            const envTurnId = `turn_${deriveStableId(['environment-context'])}`;
+            const turn0Nodes = currentNodes.filter((n) => n.turnId === envTurnId);
+            for (const n of turn0Nodes) {
+                protectedIds.add(n.id);
+            }
+            let rollingTokens = 0;
+            for (let i = currentNodes.length - 1; i >= 0; i--) {
+                const node = currentNodes[i];
+                const priorTokens = rollingTokens;
+                rollingTokens += this.env.tokenCalculator.calculateConcreteListTokens([
+                    node,
+                ]);
+                if (priorTokens > this.sidecar.config.budget.retainedTokens) {
+                    if (!protectedIds.has(node.id)) {
+                        const hasNormalizedTier = this.sidecar.config.budget.normalizedTokens !== undefined;
+                        if (!hasNormalizedTier ||
+                            priorTokens <= this.sidecar.config.budget.normalizedTokens) {
+                            agedOutRetainedNodes.add(node.id);
+                        }
+                        if (hasNormalizedTier &&
+                            priorTokens > this.sidecar.config.budget.normalizedTokens) {
+                            agedOutNormalizedNodes.add(node.id);
+                        }
+                    }
+                }
+            }
+            if (agedOutRetainedNodes.size > 0) {
+                const targetDeficit = currentTokens - this.sidecar.config.budget.retainedTokens;
+                const threshold = this.sidecar.config.budget.coalescingThresholdTokens || 0;
+                if (targetDeficit < this.lastTriggeredDeficit) {
+                    this.lastTriggeredDeficit = targetDeficit;
+                }
+                if (targetDeficit > this.lastTriggeredDeficit + threshold) {
+                    this.lastTriggeredDeficit = targetDeficit;
+                    this.eventBus.emitConsolidationNeeded({
+                        nodes: this.buffer.nodes,
+                        targetDeficit,
+                        targetNodeIds: agedOutRetainedNodes,
+                    });
+                    this.env.tokenCalculator.garbageCollectCache(new Set(this.buffer.nodes.map((n) => n.id)));
+                    this.buffer = await this.orchestrator.executeTriggerSync('nodes_aged_out', this.buffer, agedOutRetainedNodes, protectedIds);
+                }
+            }
+            else {
+                this.lastTriggeredDeficit = 0;
+            }
+            if (agedOutNormalizedNodes.size > 0) {
+                const targetDeficit = currentTokens - this.sidecar.config.budget.normalizedTokens;
+                const threshold = this.sidecar.config.budget.coalescingThresholdTokens || 0;
+                if (targetDeficit < this.lastTriggeredNormalizeDeficit) {
+                    this.lastTriggeredNormalizeDeficit = targetDeficit;
+                }
+                if (targetDeficit > this.lastTriggeredNormalizeDeficit + threshold) {
+                    this.lastTriggeredNormalizeDeficit = targetDeficit;
+                    this.eventBus.emitNormalizeNeeded({
+                        nodes: this.buffer.nodes,
+                        targetDeficit,
+                        targetNodeIds: agedOutNormalizedNodes,
+                    });
+                    this.buffer = await this.orchestrator.executeTriggerSync('normalized_exceeded', this.buffer, agedOutNormalizedNodes, protectedIds);
+                }
+            }
+            else {
+                this.lastTriggeredNormalizeDeficit = 0;
+            }
+        }
+    }
+    getProtectedNodeIds(nodes, extraProtectedIds = new Set()) {
+        const protectionMap = new Map();
+        if (nodes.length === 0)
+            return protectionMap;
+        const lastNode = nodes[nodes.length - 1];
+        const lastTurnId = lastNode.turnId;
+        // Identify Environment Context (Turn 0) for pinning
+        const envContextId = deriveStableId(['environment-context']);
+        const envContextTurnId = `turn_${envContextId}`;
+        for (const node of nodes) {
+            if (node.turnId === envContextTurnId || node.turnId === envContextId) {
+                protectionMap.set(node.id, 'environment_context');
+            }
+            if (node.turnId === lastTurnId) {
+                protectionMap.set(node.id, 'recent_turn');
+            }
+        }
+        for (const id of extraProtectedIds) {
+            protectionMap.set(id, 'external_active_task');
+        }
+        return protectionMap;
+    }
     async performHotStartCalibration(nodes, abortSignal) {
         const history = this.env.graphMapper.fromGraph(nodes);
         const contents = history.map((h) => h.content);
@@ -267,8 +315,5 @@ export class ContextManager {
             debugLogger.warn('[ContextManager] Hot start calibration failed', e);
         }
     }
-    getEnvironment() {
-        return this.env;
-    }
 }
 //# sourceMappingURL=contextManager.js.map