@caupulican/pi-adaptative 0.94.1 → 0.96.0

package/dist/core/agent-session.js

@@ -1,12 +1,11 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { basename } from "node:path";
 import { AgentBusyError } from "@caupulican/pi-agent-core/agent";
 import { compactToolResultDetailsForRetention } from "@caupulican/pi-agent-core/message-retention";
 import { createCustomMessage } from "@caupulican/pi-agent-core/messages";
-import { projectToolsForProvider } from "@caupulican/pi-agent-core/provider-tool-projection";
 import { DEFAULT_STREAM_IDLE, withStreamIdleWatchdog, } from "@caupulican/pi-agent-core/reliability";
 import { NATIVE_TOOL_PROTOCOL_RESIDUE_ERROR } from "@caupulican/pi-agent-core/tool-protocol-residue";
-import { getSupportedThinkingLevels, modelsAreEqual } from "@caupulican/pi-ai/models";
+import { modelsAreEqual } from "@caupulican/pi-ai/models";
 import { cleanupSessionResources } from "@caupulican/pi-ai/session-resources";
 import { streamSimple } from "@caupulican/pi-ai/stream";
 import { getAgentDir } from "../config.js";
@@ -22,7 +21,7 @@ import { CompactionController } from "./compaction-controller.js";
 import { CompactionSupport } from "./compaction-support.js";
 import { buildContextCompositionReport, formatContextCompositionDashboard, } from "./context/context-composition.js";
 import { ContextPipeline } from "./context-pipeline.js";
-import { downgradeReasoning, estimateTurnCostUsd, evaluateCostGuard } from "./cost-guard.js";
+import { CostGuardController } from "./cost-guard-controller.js";
 import { appendWorkerClaimSnapshot, getLatestWorkerClaimSnapshot, getWorkerClaimSnapshots, } from "./delegation/session-worker-claim.js";
 import { DurableCustomMessageTurnController } from "./durable-custom-message-turn-controller.js";
 import { ExtensionBindingController } from "./extension-binding-controller.js";
@@ -38,6 +37,7 @@ import { constrainStreamIdleToHttpTimeout } from "./http-dispatcher.js";
 import { HumanInputController } from "./human-input-controller.js";
 import { appendLearningDecisionSnapshot, getLearningDecisionSnapshots } from "./learning/session-learning-decision.js";
 import { SkillCurator } from "./learning/skill-curator.js";
+import { isWarmableLocalModel, LocalPrefixWarmController } from "./local-prefix-warm-controller.js";
 import { LocalRuntimeController } from "./local-runtime-controller.js";
 import { MemoryController } from "./memory-controller.js";
 import { deriveModelCapabilityProfile, evaluateLaneWorkerRefusal, filterToolNamesForCapability, } from "./model-capability.js";
@@ -45,8 +45,6 @@ import { isLocalOrManagedRouterModel } from "./model-router/tool-escalation.js";
 import { formatModelRouterModel, ModelRouterController } from "./model-router-controller.js";
 import { ModelSelectionController } from "./model-selection-controller.js";
 import { ModelAdaptationStore } from "./models/adaptation-store.js";
-import { HF_TRANSFORMERS_PROVIDER, OLLAMA_PROVIDER } from "./models/local-registration.js";
-import { isLoopbackModelEndpoint } from "./models/model-endpoint.js";
 import { DEFAULT_ADAPTIVE_STREAM_IDLE_CEILING_MS, estimateContextPromptTokens, resolveAdaptiveStreamIdleOptions, withModelPerfProfile, } from "./models/perf-profile.js";
 import { resolveConfiguredOrchestrationModel } from "./orchestration/model-binding.js";
 import { validateOrchestrationProfile } from "./orchestration/profile-registry.js";
@@ -129,15 +127,7 @@ export class AgentSession {
         this._turnIndex = 0;
         /** Per-agent persistent shell session identity: stable across runtime reloads, disposed with the session. */
         this._shellSessionKey = `agent:${randomUUID()}`;
-        this._completedPrefixWarms = new Set();
         this._gatewayRegistry = new GatewayRegistry();
-        /**
-         * `getSpawnedUsage().cost` snapshotted at the start of the CURRENT foreground prompt cycle (see
-         * `_promptUnserialized`), so the cost guard can attribute only background/spawned spend since THIS
-         * turn began, not the session's entire lifetime spend. Reset on every new user prompt; every
-         * round-trip within the same turn (tool-call iterations) shares this one baseline.
-         */
-        this._costGuardTurnBaselineUsd = 0;
         this._disposed = false;
         this._reflectionAbort = new AbortController();
         this._extensionMode = "print";
@@ -239,13 +229,20 @@ export class AgentSession {
                 }
             }
             if (event.type === "agent_end" && !this._willRetryAfterAgentEnd(event)) {
-                const contextHeadroomPct = Math.max(0, 100 - (this.getContextUsage()?.percent ?? 0));
-                const reflectionTurn = this._reflection.scheduleFromTurn(event.messages, contextHeadroomPct);
+                const reflectionTurn = this._reflection.analyzeCompletedTurn(event.messages);
                 // The shared projection excludes raw tool-result payloads and bounds both roles before any
-                // provider sees the turn. Synchronization is serialized in the background by MemoryController.
+                // deterministic memory sync. No reflection provider request is scheduled at this boundary.
                 this._memory.scheduleTurnSync(reflectionTurn.userText, reflectionTurn.assistantText);
+                if (reflectionTurn.trigger !== "none")
+                    this._reflection.queueCurrentTurnCue(reflectionTurn.trigger);
                 this._goals.endQueuedOwnerChatGoalExecution();
             }
+            // Error/abort turns bypass the normal steering boundary, and a completion can arrive after the
+            // final normal poll. agent_end is the fallback before foreground recovery decides whether queued
+            // steering requires one continuation; turn_end is intentionally not a flush.
+            if (event.type === "agent_end") {
+                this._terminalHandoffs.flushProviderBoundary();
+            }
         };
         this.agent = config.agent;
         // Bound every provider stream this session starts against a silently dead connection: a
@@ -264,7 +261,7 @@ export class AgentSession {
             const resolvedReasoning = previousResolveRequestReasoning
                 ? previousResolveRequestReasoning(reasoning, request)
                 : reasoning;
-            return this._resolveCostGuardRequestReasoning(request.model, request.context, resolvedReasoning, request.maxTokens);
+            return this._costGuard.resolveRequestReasoning(request.model, request.context, resolvedReasoning, request.maxTokens);
         };
         const profiledStreamFn = withModelPerfProfile(baseStreamFn, {
             modelKey: (model) => formatModelRouterModel(model),
@@ -287,7 +284,7 @@ export class AgentSession {
                 base: httpBounded.options,
                 profile,
                 promptTokens: estimateContextPromptTokens(context),
-                localClass: this._isWarmableLocalModel(model),
+                localClass: isWarmableLocalModel(model),
                 ceilingMs: httpBounded.adaptiveCeilingMs ?? DEFAULT_ADAPTIVE_STREAM_IDLE_CEILING_MS,
             });
             return { ...httpBounded.options, ...adaptive };
@@ -352,6 +349,15 @@ export class AgentSession {
             resolveConfiguredTierModel: (tier) => this._modelRouter.resolveConfiguredTierModel(tier),
             formatModel: (model) => formatModelRouterModel(model),
         });
+        this._localPrefixWarm = new LocalPrefixWarmController({
+            getStreamFn: () => this.agent.streamFn,
+            getTools: () => this.agent.state.tools,
+            getSystemPrompt: () => this._baseSystemPrompt,
+            getRequestHooks: () => ({ onPayload: this.agent.onPayload, onResponse: this.agent.onResponse }),
+            isRawStreamSimple: (streamFn) => this._isRawStreamSimple(streamFn),
+            getRequiredRequestAuth: (model) => this._getRequiredRequestAuth(model),
+            ensureManagedModelReady: (model) => this._localRuntimeController.ensureIsolatedModelReady(model),
+        });
         this._systemPromptBuilder = new SystemPromptBuilder({
             getCwd: () => this._cwd,
             getSettingsManager: () => this.settingsManager,
@@ -363,6 +369,7 @@ export class AgentSession {
             getModelAdaptationRules: () => this._toolProtocol.getAdaptationRulesForPrompt(),
             getActiveExtensions: () => this._extensionRunner.activeExtensions,
             getModelCapabilityProfile: () => this.getModelCapabilityProfile(),
+            isChildSession: () => this._isChildSession,
             // The evidence-gated tool-selection hint block — self-gated by kill switch/evidence
             // thresholds inside getActiveHints() itself, so this is a plain always-on pass-through.
             getToolSelectionHints: () => this._toolSelection.getActiveHints(),
@@ -380,6 +387,12 @@ export class AgentSession {
             getLearningAuditRecords: () => this.getLearningAuditRecords(),
         });
         this._modelRegistry = config.modelRegistry;
+        this._costGuard = new CostGuardController({
+            getSettings: () => this.settingsManager.getCostGuardSettings(),
+            getCompactionReserveTokens: () => this.settingsManager.getCompactionReserveTokens(),
+            getSpawnedUsageCost: () => this.getSpawnedUsage().cost,
+            isUnmeteredSubscription: (model) => model.provider === "openai-codex" && this._modelRegistry.isUsingOAuth(model),
+        });
         this._humanInput = new HumanInputController({
             getSessionManager: () => this.sessionManager,
             getUIContext: () => this._extensionUIContext,
@@ -414,6 +427,8 @@ export class AgentSession {
             getModelRegistry: () => this._modelRegistry,
             isModelExhausted: (model) => this._foregroundRecovery.isModelExhausted(`${model.provider}/${model.id}`),
             getModel: () => this.model ?? undefined,
+            getForegroundThinkingLevel: () => this.thinkingLevel,
+            getForegroundToolNames: () => this.getActiveToolNames(),
             isDelegateToolActive: () => this.getActiveToolNames().includes("delegate"),
             isGoalToolActive: () => hasGoalContinuationControl(this.getActiveToolNames()),
             getCapabilityEnvelope: () => this.capabilityEnvelope,
@@ -428,6 +443,15 @@ export class AgentSession {
             saveEvidenceBundleSnapshot: (bundle) => this.saveEvidenceBundleSnapshot(bundle),
             saveWorkerClaimSnapshot: (claim, request) => this.saveWorkerClaimSnapshot(claim, request),
             readMemoryForLane: (query) => this._memory.readMemoryForLane(query),
+            getArtifactStore: () => this._getToolArtifactStore(),
+            getSkillReadBroker: () => ({
+                search: (query) => this._skillVault.search(query),
+                read: (name) => this._skillVault.read(name),
+            }),
+            getSkillAuditSource: () => ({
+                getSkills: () => this._skillVault.getSkillsSnapshot(),
+                redactPath: (path) => `skill:${createHash("sha256").update(path).digest("hex").slice(0, 12)}`,
+            }),
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
             runIsolatedCompletion: (opts) => this.runIsolatedCompletion(opts),
             // RAW loop, deliberately bypassing the public `continueGoalLoop` — that method now delegates
@@ -482,6 +506,7 @@ export class AgentSession {
         });
         this._backgroundToolTasks = new BackgroundToolTaskController({
             getSessionId: () => this.sessionManager.getSessionId(),
+            getGoalId: () => this._goals.getExecutionGoalId(),
             getSessionLineageIds: () => this.sessionManager.getSessionLineageIds(),
             getArtifactStore: () => this._getToolArtifactStore(),
             loadPersistedRecordsNewestFirst: () => loadBackgroundToolTaskRecordsNewestFirst(this.sessionManager),
@@ -549,6 +574,7 @@ export class AgentSession {
             enqueueRelevanceCuration: (messages, report) => this._enqueueRelevanceCuration(messages, report),
             maybeDrainBrainCuration: () => this._maybeDrainBrainCuration(),
             appendMemoryEvidence: (messages, report) => this._maybeAppendMemoryEvidenceBlock(messages, report),
+            previewReflectionCue: () => this._reflection.previewCurrentTurnCue(),
             getGoalState: () => this.getGoalStateSnapshot(),
             skillVault: this._skillVault,
         });
@@ -587,6 +613,7 @@ export class AgentSession {
         this._durableCustomMessageTurns = new DurableCustomMessageTurnController({
             foreground: this._foregroundRecovery,
             goals: this._goals,
+            enqueueSteeringMessage: (message) => this.agent.steer(message),
         });
         this._terminalHandoffs = new ForegroundTerminalHandoffController({
             foreground: this._foregroundRecovery,
@@ -595,6 +622,7 @@ export class AgentSession {
             getWorkerClaimSnapshot: (laneId) => getLatestWorkerClaimSnapshot(getActiveSessionBranchEntries(this.sessionManager), laneId),
             getWorkerResult: (laneId) => this._backgroundLanes.getWorkerResult(laneId),
             startCustomMessageTurn: (message, lease, goalId) => this._durableCustomMessageTurns.start(message, lease, goalId),
+            enqueueCustomMessageTurn: (message) => this._durableCustomMessageTurns.enqueue(message),
             sendCustomMessage: (message, options, lease) => this._sendCustomMessage(message, options, lease),
             warn: (message) => this._emit({ type: "warning", message }),
         });
@@ -639,6 +667,8 @@ export class AgentSession {
             getSettingsManager: () => this.settingsManager,
             getSessionManager: () => this.sessionManager,
             getAgentDir: () => this._agentDir,
+            getCwd: () => this._cwd,
+            getSkillsForAudit: () => this._resourceLoader.getActiveSkills(),
             isChildSession: () => this._isChildSession,
             isDisposed: () => this._disposed,
             getReflectionSignal: () => this._reflectionAbort.signal,
@@ -957,79 +987,15 @@ export class AgentSession {
             activeToolNames: this._initialActiveToolNames,
             includeAllExtensionTools: true,
         });
-        this._scheduleLocalPrefixWarm(this.agent.state.model, "session-start");
+        this._unsubscribeSettingsChanges = this.settingsManager.subscribeChanges(() => {
+            this._refreshBaseSystemPrompt();
+        });
+        this._localPrefixWarm.schedule(this.agent.state.model);
     }
     /** Model registry for API key resolution and model discovery */
     get modelRegistry() {
         return this._modelRegistry;
     }
-    _scheduleLocalPrefixWarm(model, _reason) {
-        if (!model || !this._isWarmableLocalModel(model))
-            return;
-        const modelKey = formatModelRouterModel(model);
-        if (this._completedPrefixWarms.has(modelKey) || this._prefixWarmer?.modelKey === modelKey)
-            return;
-        this._cancelPrefixWarm();
-        const controller = new AbortController();
-        const timer = setTimeout(() => {
-            const warmer = this._prefixWarmer;
-            if (!warmer || warmer.controller !== controller || controller.signal.aborted)
-                return;
-            warmer.timer = undefined;
-            void this._runLocalPrefixWarm(model, modelKey, controller);
-        }, 0);
-        timer.unref?.();
-        this._prefixWarmer = { modelKey, controller, timer };
-    }
-    _cancelPrefixWarm() {
-        const warmer = this._prefixWarmer;
-        if (!warmer)
-            return;
-        if (warmer.timer)
-            clearTimeout(warmer.timer);
-        warmer.controller.abort(new Error("prefix warmer preempted"));
-        this._prefixWarmer = undefined;
-    }
-    async _runLocalPrefixWarm(model, modelKey, controller) {
-        try {
-            const options = {
-                maxTokens: 1,
-                signal: controller.signal,
-                onPayload: this.agent.onPayload,
-                onResponse: this.agent.onResponse,
-            };
-            if (this._isRawStreamSimple(this.agent.streamFn)) {
-                const auth = await this._getRequiredRequestAuth(model);
-                options.apiKey = auth.apiKey;
-                options.headers = auth.headers;
-            }
-            if (controller.signal.aborted)
-                return;
-            if (model.provider === OLLAMA_PROVIDER || model.provider === HF_TRANSFORMERS_PROVIDER) {
-                await this._localRuntimeController.ensureIsolatedModelReady(model);
-            }
-            if (controller.signal.aborted)
-                return;
-            const stream = await this.agent.streamFn(model, {
-                systemPrompt: this._baseSystemPrompt,
-                tools: projectToolsForProvider(this.agent.state.tools),
-                messages: [],
-            }, options);
-            await stream.result();
-            if (!controller.signal.aborted)
-                this._completedPrefixWarms.add(modelKey);
-        }
-        catch {
-            // Best-effort cache warm only; a miss must never affect the real turn.
-        }
-        finally {
-            if (this._prefixWarmer?.controller === controller)
-                this._prefixWarmer = undefined;
-        }
-    }
-    _isWarmableLocalModel(model) {
-        return model.api === "openai-completions" && isLoopbackModelEndpoint(model.baseUrl);
-    }
     /**
      * True when the session's stream fn is the raw `streamSimple` provider entry (directly, or as the
      * base wrapped by the idle watchdog at construction). Callers use this to decide whether request
@@ -1084,58 +1050,16 @@ export class AgentSession {
     _resolveCompactionThinkingLevel(compactionModel, sessionModel) {
         return this._compactionSupport.resolveThinkingLevel(this.thinkingLevel, compactionModel, sessionModel);
     }
-    /**
-     * Resolve the foreground request's cost policy after routing/context conversion, when the actual
-     * model, full system prompt, converted messages, and tool schemas are known. The guard is a
-     * projection threshold rather than a hard output cap: warning mode never reduces capability, while
-     * opt-in downgrade changes only this request's reasoning effort. Best-effort: never throws.
-     *
-     * The ceiling is turn-cumulative: the next foreground call's projection is folded together with
-     * background/research/worker/reflection spend recorded SINCE THIS TURN BEGAN — {@link getSpawnedUsage}'s
-     * already-recorded rollup (the same read-side-deduped total the footer's SUBAGENTS line uses) minus the
-     * baseline snapshotted before a new turn enters routing in `_promptUnserialized`
-     * ({@link _costGuardTurnBaselineUsd}) — so a
-     * turn that is cheap in the foreground but has spent heavily via background lanes THIS turn still trips
-     * the warning, while a prior turn's background spend does not keep every later turn's guard stuck
-     * "over". A background lane that finishes mid-turn is attributed to whichever turn it completes in.
-     * Per-lane dollar caps (research/worker `maxUsd`) are separate and untouched by this guard.
-     */
-    _resolveCostGuardRequestReasoning(model, context, reasoning, requestMaxTokens) {
-        try {
-            const guard = this.settingsManager.getCostGuardSettings();
-            const isChatGptSubscription = model.provider === "openai-codex" && this._modelRegistry.isUsingOAuth(model);
-            if (guard.maxTurnUsd <= 0 || !model.cost || isChatGptSubscription) {
-                this._lastCostGuardDecision = undefined;
-                return reasoning;
-            }
-            const inputTokens = estimateContextPromptTokens(context);
-            // Use an explicit request cap when present; otherwise project against the session response
-            // reserve instead of a frontier model's theoretical 128K output maximum.
-            const maxOutputTokens = Math.min(model.maxTokens ?? 4096, requestMaxTokens ?? this.settingsManager.getCompactionReserveTokens());
-            const estUsd = estimateTurnCostUsd({
-                inputTokens,
-                maxOutputTokens,
-                cost: model.cost,
-                longContextPricing: model.longContextPricing,
-            });
-            // Only spend recorded SINCE this turn's baseline counts -- never negative (a dedup/rollup
-            // correction could otherwise move the total backward transiently).
-            const cumulativeBackgroundUsd = Math.max(0, this.getSpawnedUsage().cost - this._costGuardTurnBaselineUsd);
-            const decision = evaluateCostGuard(estUsd, { maxTurnUsd: guard.maxTurnUsd, action: guard.action }, cumulativeBackgroundUsd);
-            this._lastCostGuardDecision = decision;
-            if (!decision.over || guard.action !== "downgrade" || reasoning === undefined)
-                return reasoning;
-            const next = downgradeReasoning(reasoning, getSupportedThinkingLevels(model), model.thinkingLevelMap);
-            return next;
-        }
-        catch {
-            // cost guard must never disrupt a turn
-            return reasoning;
-        }
-    }
     /** Latest cost-guard decision (for the host footer/UI to surface a warning). Undefined if disabled. */
     getLastCostGuardDecision() {
-        return this._lastCostGuardDecision;
+        return this._costGuard.getLastDecision();
+    }
+    /** Apply an explicit guard choice and invalidate all prior decision/envelope projections immediately. */
+    setCostGuardSettings(settings, scope = "global") {
+        this.settingsManager.setCostGuardSettings(settings, scope);
+        this._costGuard.invalidateDecision();
+        if (this._currentForegroundEnvelope)
+            this._refreshForegroundEnvelope();
     }
     get _skillCurator() {
         if (!this._skillCuratorInstance) {
@@ -1179,6 +1103,13 @@ export class AgentSession {
     }
     _installAgentTurnRefresh() {
         const previousPrepareNextTurn = this.agent.prepareNextTurn?.bind(this.agent);
+        const previousBeforeSteeringPoll = this.agent.beforeSteeringPoll?.bind(this.agent);
+        this.agent.beforeSteeringPoll = async (signal) => {
+            await previousBeforeSteeringPoll?.(signal);
+            // This is later than async turn preparation and the graceful-stop check, making it the
+            // authoritative last-moment inbox refresh before the queue is drained.
+            this._terminalHandoffs.flushProviderBoundary();
+        };
         this.agent.prepareNextTurn = async (signal) => {
             const previous = previousPrepareNextTurn ? await previousPrepareNextTurn(signal) : undefined;
             const snapshot = this._createAgentContextSnapshot();
@@ -1741,18 +1672,21 @@ export class AgentSession {
         safely(() => this._backgroundLanes.clearGoalAutoContinueTimer());
         safely(() => this._backgroundLanes.clearResearchLaneTimer());
         safely(() => this._foregroundRecovery.shutdown());
+        safely(() => this._durableCustomMessageTurns.shutdown());
         safely(() => this.abortRetry());
         safely(() => this.abortCompaction());
         safely(() => this.abortBranchSummary());
         safely(() => this.abortBash());
         safely(() => this._skillVault.unload());
+        safely(() => this._unsubscribeSettingsChanges?.());
+        this._unsubscribeSettingsChanges = undefined;
         trackRequired(() => disposeShellExecutionSessionAndWait(this._shellSessionKey));
-        safely(() => this._cancelPrefixWarm());
+        safely(() => this._localPrefixWarm.cancel());
         safely(() => this.agent.abort());
         track(() => this._gatewayRegistry.stop());
         track(() => this._backgroundToolTasks.shutdown());
         track(() => this._runtimeBuilder.dispose());
-        safely(() => this._reflection.cancelScheduled());
+        safely(() => this._reflection.dispose());
         safely(() => this._reflectionAbort.abort());
         safely(() => this._backgroundLanes.abortInFlightLanes());
         safely(() => this._providerRequestRuntime.dispose());
@@ -1765,12 +1699,7 @@ export class AgentSession {
         track(() => this._resourceLoader.dispose?.() ?? Promise.resolve());
         safely(() => this._disconnectFromAgent());
         this._eventListeners = [];
-        // Let an aborted in-flight reflection reach its terminal state, then flush session-owned write
-        // hooks before releasing provider locks/handles. This prevents a late write racing shutdown.
-        track(async () => {
-            await this._reflection.waitForActivePass();
-            await this._memory.shutdown();
-        });
+        track(() => this._memory.shutdown());
         track(() => this._toolRecoveryLogger.shutdown());
         safely(() => cleanupSessionResources(this.sessionId));
         // Best-effort final sweep for any grep/find artifact already released (reference
@@ -1828,7 +1757,7 @@ export class AgentSession {
             turnIndex: this._turnIndex,
             activeToolNames: this.getActiveToolNames(),
             cwd: this._cwd,
-            maxTurnUsd: this.settingsManager.getCostGuardSettings().maxTurnUsd,
+            maxTurnUsd: this._costGuard.getEnabledMaxTurnUsd(),
         });
     }
     /**
@@ -2090,7 +2019,7 @@ export class AgentSession {
     }
     async _promptUnserialized(text, options, submission) {
         this._toolProtocol.applyRepairLayerSettings();
-        this._cancelPrefixWarm();
+        this._localPrefixWarm.cancel();
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const processSlashCommands = options?.processSlashCommands ?? expandPromptTemplates;
         const preflightResult = options?.preflightResult;
@@ -2175,9 +2104,9 @@ export class AgentSession {
             if (!options?.internalContextType) {
                 admittedGoalId = this._goals.startOwnerChatGoal(expandedText, this.agent.state.messages) ?? admittedGoalId;
             }
-            // This submission is starting a new foreground turn. Queued steer/follow-up messages above
-            // remain part of the already-active turn and must not erase its spawned-cost baseline.
-            this._costGuardTurnBaselineUsd = this.getSpawnedUsage().cost;
+            // Queued steer/follow-up messages remain in the active turn; only a new submission resets the
+            // cost controller's spawned-usage baseline shared by every round trip in this turn.
+            this._costGuard.beginForegroundTurn();
             // Flush any pending bash messages before the new prompt
             this._flushPendingBashMessages();
             // Build the user message now — before the router judge — and paint it to the UI
@@ -2274,6 +2203,10 @@ export class AgentSession {
                     // recall must never break a turn
                 }
             }
+            // Queue one durable logical cue. ProviderRequestContextController owns its transient preview
+            // and accepted-plan commit, so it never enters or needs cleanup from agent history.
+            if (!options?.internalContextType)
+                this._reflection.queueCurrentTurnCue("root-turn");
             // Add user message (built earlier, before the router judge, so it could be painted
             // immediately — see the early message_start emit above).
             messages.push(promptMessage);
@@ -2654,7 +2587,7 @@ export class AgentSession {
     // =========================================================================
     async setModel(model, options = {}) {
         await this._modelSelection.setModel(model, options);
-        this._scheduleLocalPrefixWarm(this.agent.state.model, "selection");
+        this._localPrefixWarm.schedule(this.agent.state.model);
     }
     /** Re-resolve startup profile model/thinking after allowed extension providers are bound. */
     async reapplyActiveProfileModelSettings() {
@@ -2663,12 +2596,12 @@ export class AgentSession {
         const activeToolNames = this._requestedActiveToolNames ?? this.getActiveToolNames();
         this._refreshToolRegistry({ activeToolNames, includeAllExtensionTools: true });
         if (!modelsAreEqual(previousModel, this.model)) {
-            this._scheduleLocalPrefixWarm(this.model, "selection");
+            this._localPrefixWarm.schedule(this.model);
         }
     }
     async cycleModel(direction = "forward") {
         const result = await this._modelSelection.cycleModel(direction);
-        this._scheduleLocalPrefixWarm(result?.model, "selection");
+        this._localPrefixWarm.schedule(result?.model);
         return result;
     }
     // =========================================================================
@@ -2839,6 +2772,7 @@ export class AgentSession {
     }
     async reload() {
         this._foregroundLifecycle.reload();
+        this._reflection.invalidateCurrentTurnCueStateCache();
         this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
         return this._runtimeBuilder.reload();
     }
@@ -2928,7 +2862,9 @@ export class AgentSession {
     // Tree Navigation
     // =========================================================================
     async navigateTree(targetId, options = {}) {
-        return this._treeNavigator.navigateTree(targetId, options);
+        const result = await this._treeNavigator.navigateTree(targetId, options);
+        this._reflection.invalidateCurrentTurnCueStateCache();
+        return result;
     }
     getUserMessagesForForking() {
         return this._treeNavigator.getUserMessagesForForking();
@@ -3124,16 +3060,13 @@ export class AgentSession {
     async continueGoalLoop(options) {
         return this._backgroundLanes.continueGoalLoopExclusive(options);
     }
-    /**
-     * Run a one-shot LLM completion fully ISOLATED from the main session — the load-bearing primitive
-     * for native reflection (see reflection-controller.ts for the isolation invariants).
-     */
+    /** Run one explicit isolated completion for bounded host-owned consumers. */
     async runIsolatedCompletion(opts) {
         return this._reflection.runIsolatedCompletion(opts);
     }
     /**
-     * Native end-of-loop reflection pass. Delegates to {@link ReflectionController}; returns null
-     * when the demand gate skips or in a child session.
+     * Explicit compatibility/application reflection pass. Automatic reflection never calls this
+     * method; it returns null when the demand gate skips or in a child session.
      */
     async runReflectionPass(input) {
         return this._reflection.runReflectionPass(input);