@caupulican/pi-adaptative 0.81.37 → 0.81.39

package/dist/core/agent-session.js

@@ -1,12 +1,14 @@
+import { createHash, randomUUID } from "node:crypto";
 import { readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { classifyFailure, compactToolResultDetailsForRetention, computeRetryDelayMs, createCustomMessage, DEFAULT_RETRY_POLICY, DEFAULT_STREAM_IDLE, RetryController, sleepAbortable, withStreamIdleWatchdog, } from "@caupulican/pi-agent-core";
 import { calculateContextTokens, compact, createDeterministicCompaction, estimateContextTokens, getLatestCompactionEntry, prepareCompaction, runCompactionLoop, shouldCompact, } from "@caupulican/pi-agent-core/node";
-import { cleanupSessionResources, formatToolRepairStandingRule, generateTextToolProtocolPrimer, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, parseTextToolCalls, streamSimple, } from "@caupulican/pi-ai";
+import { cleanupSessionResources, formatToolRepairStandingRule, formatVariantEnvelope, generateTextToolProtocolPrimer, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, parseTextToolCalls, streamSimple, } from "@caupulican/pi-ai";
 import { Type } from "typebox";
 import { getAgentDir } from "../config.js";
 import { stripFrontmatter } from "../utils/frontmatter.js";
 import { getProcessWorkRun } from "../utils/work-directory.js";
+import { resourceDir, stateFile } from "./agent-paths.js";
 import { formatNoApiKeyFoundMessage, formatNoModelSelectedMessage } from "./auth-guidance.js";
 import { buildForegroundEnvelope, formatForegroundEnvelopeObservation } from "./autonomy/foreground-envelope.js";
 import { evaluateToolGate } from "./autonomy/gates.js";
@@ -23,16 +25,18 @@ import { FailureCorpusRecorder } from "./failure-corpus.js";
 import { GatewayRegistry } from "./gateways/channel-provider.js";
 import { GoalLoopController } from "./goal-loop-controller.js";
 import { buildGoalRuntimeSnapshot, } from "./goals/goal-runtime-snapshot.js";
+import { applyGoalEvent } from "./goals/goal-state.js";
 import { appendGoalStateSnapshot, getLatestGoalStateSnapshot } from "./goals/session-goal-state.js";
 import { constrainStreamIdleToHttpTimeout } from "./http-dispatcher.js";
 import { appendLearningDecisionSnapshot, getLearningDecisionSnapshots } from "./learning/session-learning-decision.js";
 import { isPromotedFrontmatter, SkillCurator } from "./learning/skill-curator.js";
 import { LocalRuntimeController } from "./local-runtime-controller.js";
 import { MemoryController } from "./memory-controller.js";
-import { deriveModelCapabilityProfile, filterToolNamesForCapability, } from "./model-capability.js";
+import { deriveModelCapabilityProfile, evaluateLaneWorkerRefusal, filterToolNamesForCapability, } from "./model-capability.js";
+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 { ModelAdaptationStore, } from "./models/adaptation-store.js";
 import { HF_TRANSFORMERS_PROVIDER, OLLAMA_PROVIDER } from "./models/local-registration.js";
 import { DEFAULT_ADAPTIVE_STREAM_IDLE_CEILING_MS, estimateContextPromptTokens, resolveAdaptiveStreamIdleOptions, withModelPerfProfile, } from "./models/perf-profile.js";
 import { ProfileFilterController } from "./profile-filter-controller.js";
@@ -53,7 +57,8 @@ import { ToolRecoveryLogger } from "./tool-recovery-logger.js";
 import { formatToolRepairHealthReport } from "./tool-repair-health.js";
 import { resolveCurrentToolRepairSettings } from "./tool-repair-settings.js";
 import { ToolPerformanceStore } from "./tool-selection/tool-performance-store.js";
-import { ToolSelectionController } from "./tool-selection/tool-selection-controller.js";
+import { formatToolSelectionReport, ToolSelectionController } from "./tool-selection/tool-selection-controller.js";
+import { disposePersistentShellSession } from "./tools/shell-session.js";
 // ============================================================================
 // Stream-idle watchdog wiring
 // ============================================================================
@@ -71,6 +76,19 @@ const MODEL_ADAPTATION_REPAIR_THRESHOLD = 3;
 const TEXT_TOOL_PROTOCOL_VERSION = 1;
 const TEXT_TOOL_PROTOCOL_TRIALS_PER_VARIANT = 2;
 const TEXT_TOOL_PROTOCOL_PARSE_FAILURE_THRESHOLD = 3;
+/** How often the one-line envelope-format corrective steer (see
+ * {@link AgentSession._maybeInjectTextProtocolCorrectiveSteer}) re-fires after the first parse
+ * failure this session — every Nth failure thereafter, not every single one, so a model that keeps
+ * missing the envelope doesn't get the reminder spliced into every turn (the breaker's same-signature
+ * counter is what actually demotes it, at {@link TEXT_TOOL_PROTOCOL_PARSE_FAILURE_THRESHOLD}). */
+const TEXT_TOOL_PROTOCOL_STEER_INTERVAL = 5;
+/** Anti-loop cooldown: the evidence-gated auto-probe (see {@link
+ * AgentSession._maybeAutoProbeOnValidationEscalation}) skips a model whose persisted `toolProbe`
+ * verdict was written within this window, so a burst of validation-escalation events for a still-
+ * failing model — or a very recent explicit `/toolprobe` run, or a future circuit-breaker demote — does
+ * not re-fire the (multi-completion) probe every time. Independent of, and complementary to, the
+ * per-session `_autoProbedModels` latch. */
+const AUTO_TOOL_PROBE_FRESHNESS_MS = 15 * 60 * 1000;
 const TEXT_TOOL_PROTOCOL_VARIANTS = [
     "tool-tag",
     "tool-call",
@@ -123,6 +141,43 @@ export function parseSkillBlock(text) {
 }
 /** customType for spawned-usage roll-up entries (Cost Aggregation, Model A). */
 export const SPAWNED_USAGE_CUSTOM_TYPE = "spawned_usage";
+/**
+ * customType for a persisted runaway-loop-backstop entry: the agent loop stopped a turn stuck
+ * repeating one identical tool-call signature. This is the session-log/telemetry sink for
+ * {@link Agent.onRunawayStop} — see `_installAgentToolHooks`.
+ */
+export const RUNAWAY_STOP_CUSTOM_TYPE = "runaway_stop";
+/**
+ * customType for a persisted tool-validation-escalation entry: the agent loop bounced the same
+ * tool-call validation failure enough times to escalate. This is the session-log/telemetry sink for
+ * {@link Agent.onToolValidationEscalation} — see `_installAgentToolHooks`.
+ */
+export const TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE = "tool_validation_escalation";
+/** Fallback {@link IsolatedCompletionOptions.laneKind} for callers that do not tag their lane. */
+export const DEFAULT_ISOLATED_LANE_KIND = "isolated";
+/**
+ * Derive a STABLE synthetic cache-affinity key for an isolated completion lane. Isolated calls
+ * deliberately never carry the real session id (see reflection-controller.ts's isolation invariants —
+ * an isolated call must not entangle with the main session), which today also means every isolated
+ * call looks like a brand-new, uncorrelated session to providers with session-affinity headers /
+ * `prompt_cache_key` (anthropic.ts's `x-session-affinity`, openai-responses.ts /
+ * openai-completions.ts's `prompt_cache_key`), defeating their cache routing.
+ *
+ * This key is deterministic per `(laneKind, model, systemPrompt)` — the SAME lane calling the SAME
+ * model with the SAME (static) system prompt always gets the SAME key, so repeat calls route to the
+ * same cache-warm backend — while remaining fully synthetic: it is a salted hash, namespaced with a
+ * `lane:` prefix, and never derived from or equal to the real session id.
+ */
+export function computeLaneAffinityKey(laneKind, model, systemPrompt) {
+    const modelKey = model ? `${model.provider}/${model.id}` : "unknown-model";
+    // NUL-separated fields: laneKind/modelKey are drawn from small caller-controlled vocabularies
+    // that never contain a raw NUL, so this cannot field-collide the way a plain colon/space join could.
+    const digest = createHash("sha256")
+        .update(["pi-lane-affinity-v1", laneKind, modelKey, systemPrompt].join("\u0000"))
+        .digest("hex")
+        .slice(0, 32);
+    return `lane:${laneKind}:${digest}`;
+}
 // ============================================================================
 // Constants
 // ============================================================================
@@ -166,6 +221,8 @@ export class AgentSession {
     _resourceLoader;
     _customTools;
     _cwd;
+    /** Per-agent persistent shell session identity: stable across runtime reloads, disposed with the session. */
+    _shellSessionKey = `agent:${randomUUID()}`;
     _agentDir;
     _collectWorkspaceSources;
     _localRuntimeController;
@@ -175,11 +232,22 @@ export class AgentSession {
     _repairModeSessionCounts = new Map();
     _textProtocolParseFailures = new Map();
     _textProtocolParseObservedThisTurn = false;
+    /** Total text-protocol parse-failure events observed this session, backing the
+     * {@link TEXT_TOOL_PROTOCOL_STEER_INTERVAL} throttle on {@link _maybeInjectTextProtocolCorrectiveSteer}. */
+    _textProtocolCorrectiveSteerCount = 0;
+    /** Monotonic counter backing tool-probe/text-protocol-calibration spawned-usage reportIds
+     * (see {@link _nextProbeUsageReportId}); guarantees each probe/calibration completion in the
+     * session lands in the cost ledger exactly once, even across repeated /toolprobe invocations. */
+    _toolProbeUsageReportSeq = 0;
+    /** Anti-loop: modelKeys the evidence-gated auto-probe has already fired for THIS session (see
+     * {@link _maybeAutoProbeOnValidationEscalation}), so a burst of validation-escalation events for
+     * the same still-failing model never re-fires the probe more than once per session. */
+    _autoProbedModels = new Set();
     _textProtocolValidationOutcomeThisTurn;
     /** Assembles the session's base system prompt from live session state (see
      * system-prompt-builder.ts); owns the paired _baseSystemPromptOptions. */
     _systemPromptBuilder;
-    /** G3/G8 autonomy telemetry sink + status/diagnostic snapshots (see autonomy-telemetry.ts); owns
+    /** Autonomy telemetry sink + status/diagnostic snapshots (see autonomy-telemetry.ts); owns
      * the latest gate outcome and the bounded gate-outcome history. */
     _autonomyTelemetry;
     /** Goal auto-continue + research lane + scout-worker delegation + model-fitness probe (see
@@ -208,6 +276,13 @@ export class AgentSession {
     _analytics;
     _treeNavigator;
     _lastCostGuardDecision;
+    /**
+     * `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.
+     */
+    _costGuardTurnBaselineUsd = 0;
     /** Per-turn model-router subsystem (see model-router-controller.ts); owns the transient route/intent,
      * the cheap-turn session buffer, the escalation/retry flags, and the sticky last-decision/skip-reason
      * used by the status report. Its parallel routed drive path delegates every turn back to
@@ -339,6 +414,9 @@ export class AgentSession {
             getActiveExtensions: () => this._extensionRunner.activeExtensions,
             getContextWindow: () => this.model?.contextWindow,
             getThinkingLevel: () => this.thinkingLevel,
+            // 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(),
         });
         this._autonomyTelemetry = new AutonomyTelemetry({
             getSessionManager: () => this.sessionManager,
@@ -365,6 +443,7 @@ export class AgentSession {
             isModelExhausted: (model) => this._billingFailover.isExhausted(`${model.provider}/${model.id}`),
             getModel: () => this.model ?? undefined,
             isDelegateToolActive: () => this.getActiveToolNames().includes("delegate"),
+            isGoalToolActive: () => this.getActiveToolNames().includes("goal"),
             getCapabilityEnvelope: () => this.capabilityEnvelope,
             getModelCapabilityProfile: () => this.getModelCapabilityProfile(),
             emit: (event) => this._emit(event),
@@ -378,7 +457,10 @@ export class AgentSession {
             readMemoryForLane: (query) => this._memory.readMemoryForLane(query),
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
             runIsolatedCompletion: (opts) => this.runIsolatedCompletion(opts),
-            continueGoalLoop: (options) => this.continueGoalLoop(options),
+            // RAW loop, deliberately bypassing the public `continueGoalLoop` — that method now delegates
+            // to this controller's own `continueGoalLoopExclusive` guard, so routing through it here would
+            // recurse into the guard from inside itself instead of driving the actual continuation pass.
+            continueGoalLoop: (options) => this._goalContinuation.continueGoalLoop(options),
             collectWorkspaceSources: (args) => this._collectWorkspaceSources(args),
         });
         this._memory = new MemoryController({
@@ -404,6 +486,10 @@ export class AgentSession {
             // conservative in the safe direction for the summarizer capacity check.
             estimateSummarizationInputTokens: () => this._pipeline.estimateCurrentContextTokens(this.agent.state.messages),
             emitWarning: (message) => this._emit({ type: "warning", message }),
+            // Route a managed-local summarizer through the same readiness/residency gate every
+            // other isolated consumer uses, so compact() never calls a local model that was never
+            // confirmed up, installed, or resident (no-op for cloud models).
+            ensureModelReady: (model) => this._localRuntimeController.ensureIsolatedModelReady(model),
         });
         this._pipeline = new ContextPipeline({
             getTurnIndex: () => this._turnIndex,
@@ -419,8 +505,8 @@ export class AgentSession {
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
             runIsolatedCompletion: (opts) => this.runIsolatedCompletion(opts),
         });
-        const failureCorpusPath = join(this._agentDir, "state", "failure-corpus.jsonl");
-        this._toolRecoveryEventLogPath = join(this._agentDir, "state", TOOL_RECOVERY_EVENT_LOG_FILE);
+        const failureCorpusPath = stateFile(this._agentDir, "failure-corpus.jsonl");
+        this._toolRecoveryEventLogPath = stateFile(this._agentDir, TOOL_RECOVERY_EVENT_LOG_FILE);
         const toolRepairSettings = this._toolRepairSettings();
         this._failureCorpus = new FailureCorpusRecorder({
             filePath: failureCorpusPath,
@@ -459,6 +545,7 @@ export class AgentSession {
             emitAutonomyTelemetry: (event) => this._emitAutonomyTelemetry(event),
             resolveLaneModel: (pattern) => this._backgroundLanes.resolveLaneModel(pattern),
             resolveCurationModelIfFit: () => this._resolveCurationModelIfFit(),
+            getToolProbeVerdict: (model) => this._toolProbeVerdict(model),
         });
         this._reflection = new ReflectionController({
             getModel: () => this.model,
@@ -482,6 +569,7 @@ export class AgentSession {
         this._goalContinuation = new GoalLoopController({
             getGoalRuntimeSnapshot: (settings) => this.getGoalRuntimeSnapshot(settings),
             prompt: (text, options) => this.prompt(text, options),
+            recordGoalContinuationPass: (pass) => this.recordGoalContinuationPass(pass),
         });
         this._extensionRunnerRef = config.extensionRunnerRef;
         this._initialActiveToolNames = config.initialActiveToolNames;
@@ -498,6 +586,7 @@ export class AgentSession {
         this._runtimeBuilder = new RuntimeBuilder({
             getAgent: () => this.agent,
             getCwd: () => this._cwd,
+            getShellSessionKey: () => this._shellSessionKey,
             getAgentDir: () => this._agentDir,
             getSessionManager: () => this.sessionManager,
             getSettingsManager: () => this.settingsManager,
@@ -560,11 +649,13 @@ export class AgentSession {
             startWorkerDelegation: (request) => this._backgroundLanes.startWorkerDelegation(request),
             getWorkerLaneRecords: () => this._backgroundLanes.getLaneRecords(),
             getWorkerResultSnapshots: () => this.getWorkerResultSnapshots(),
+            resolveManagedLaneId: (id) => this._backgroundLanes.resolveManagedLaneId(id),
             runWorkerDelegationOnce: (request) => this.runWorkerDelegationOnce(request),
             runModelFitness: (args) => this.runModelFitness(args),
             resolveCurationModelIfFit: () => this._resolveCurationModelIfFit(),
             runIsolatedCompletion: (opts) => this.runIsolatedCompletion(opts),
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
+            getLaneWorkerRefusal: () => this.getLaneWorkerRefusal(),
             createAgentContextSnapshot: () => this._createAgentContextSnapshot(),
             getContextUsage: () => this.getContextUsage(),
             isStreaming: () => this.isStreaming,
@@ -573,6 +664,10 @@ export class AgentSession {
             getExtensionCommandContextActions: () => this._extensionCommandContextActions,
             getExtensionShutdownHandler: () => this._extensionShutdownHandler,
             getExtensionErrorListener: () => this._extensionErrorListener,
+            // Stop any pi-spawned local runtime the just-committed reload no longer routes to.
+            reconcileLocalRuntimes: () => {
+                this._localRuntimeController.reconcile(this._collectEligibleLocalModelsForReconcile());
+            },
         });
         this._analytics = new SessionAnalytics({
             getState: () => this.state,
@@ -633,6 +728,7 @@ export class AgentSession {
             getSessionManager: () => this.sessionManager,
             getSettingsManager: () => this.settingsManager,
             isStreaming: () => this.isStreaming,
+            getShellSessionKey: () => this._shellSessionKey,
         });
         this._profileFilter = new ProfileFilterController({
             getSettingsManager: () => this.settingsManager,
@@ -847,13 +943,30 @@ export class AgentSession {
                 const settings = this._getAdaptedCompactionSettings();
                 const contextWindow = this.model?.contextWindow ?? 0;
                 if (settings.enabled && contextWindow > 0 && !this.isCompacting) {
+                    const triggerTokens = this.model?.autoCompactionTriggerTokens;
                     const contextTokens = this._estimateCurrentContextTokens(authoritativeMessages);
-                    if (shouldCompact(contextTokens, contextWindow, settings, this.model?.autoCompactionTriggerTokens)) {
-                        const latestBefore = getLatestCompactionEntry(this.sessionManager.getBranch())?.id;
-                        await this._runAutoCompaction("threshold", false);
-                        const latestAfter = getLatestCompactionEntry(this.sessionManager.getBranch())?.id;
-                        if (latestAfter && latestAfter !== latestBefore) {
-                            currentMessages = this.agent.state.messages.slice();
+                    if (shouldCompact(contextTokens, contextWindow, settings, triggerTokens)) {
+                        // This pre-check runs BEFORE context-gc (below, same transform pass), so the
+                        // raw estimate above can't see this turn's own GC packing. Since context-gc later
+                        // packs the SAME messages before they're ever sent, a raw-over-threshold turn that
+                        // GC alone would bring back under threshold doesn't actually need compaction.
+                        // Project this turn's GC pass read-only (writePayloads=false -- no digest/curation
+                        // enqueue, no disk write, no artifact-reference release; see
+                        // ContextPipeline.applyContextGc) to get the same packed output the real pass would
+                        // produce for these messages, then re-check against ITS estimate. Packing only ever
+                        // shrinks (never grows) a message, so the projected estimate is never higher than
+                        // the raw one: this can only SUPPRESS an unnecessary compaction, never skip a
+                        // genuinely needed one -- the hard near-full trigger inside shouldCompact still
+                        // fires whenever the projected estimate itself remains over threshold.
+                        const gcProjection = this._applyContextGc(authoritativeMessages, false);
+                        const projectedContextTokens = this._estimateCurrentContextTokens(gcProjection.messages);
+                        if (shouldCompact(projectedContextTokens, contextWindow, settings, triggerTokens)) {
+                            const latestBefore = getLatestCompactionEntry(this.sessionManager.getBranch())?.id;
+                            await this._runAutoCompaction("threshold", false);
+                            const latestAfter = getLatestCompactionEntry(this.sessionManager.getBranch())?.id;
+                            if (latestAfter && latestAfter !== latestBefore) {
+                                currentMessages = this.agent.state.messages.slice();
+                            }
                         }
                     }
                 }
@@ -888,6 +1001,15 @@ export class AgentSession {
      * 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 at the top of `_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 {
@@ -907,7 +1029,10 @@ export class AgentSession {
                 cost: model.cost,
                 longContextPricing: model.longContextPricing,
             });
-            const decision = evaluateCostGuard(estUsd, { maxTurnUsd: guard.maxTurnUsd, action: guard.action });
+            // 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;
@@ -925,7 +1050,7 @@ export class AgentSession {
     }
     get _skillCurator() {
         if (!this._skillCuratorInstance) {
-            this._skillCuratorInstance = new SkillCurator(join(this._agentDir, "skills"));
+            this._skillCuratorInstance = new SkillCurator(resourceDir("skills", this._agentDir));
         }
         return this._skillCuratorInstance;
     }
@@ -1024,6 +1149,28 @@ export class AgentSession {
         }
         return this.agent.streamFn(model, context, requestOptions);
     }
+    /** Builds a reportId that uniquely identifies one probe/calibration completion within the
+     * session: the model, a caller-supplied `kind` (e.g. "read-task", "echo", or
+     * "text-protocol:<variant>"), and a monotonic sequence number. The sequence number (not
+     * wall-clock time or randomness) is what guarantees no collision even when the same model+kind
+     * is probed again later in the session (e.g. a repeated /toolprobe run), so genuine repeat spend
+     * is never silently deduped away. */
+    _nextProbeUsageReportId(model, kind) {
+        return `tool-probe:${this._modelRef(model)}:${kind}:${this._toolProbeUsageReportSeq++}`;
+    }
+    /** Awaits a tool-probe/text-protocol-calibration stream's result and, if the resolved message
+     * carries reportable usage, rolls it into spawned usage under `reportId` so the turn-scoped cost
+     * guard and daily usage see it. These trial completions previously spent tokens with no
+     * addSpawnedUsage call, making them invisible to both. `addSpawnedUsage` dedups on `reportId`, so
+     * a re-report of the same id is a no-op. */
+    async _resolveProbeStreamCountingUsage(stream, label, reportId) {
+        const message = await stream.result();
+        const usage = message.usage;
+        if (usage && (usage.cost.total > 0 || usage.totalTokens > 0)) {
+            this.addSpawnedUsage(usage, { label, reportId });
+        }
+        return message;
+    }
     _textProtocolCalibrationContext(variant, token) {
         const primer = generateTextToolProtocolPrimer([TEXT_TOOL_PROTOCOL_ECHO_TOOL], { variant });
         const instruction = `Text tool protocol calibration trial. Using the protocol above, call echo with data exactly "${token}". Output only the tool-call envelope.`;
@@ -1055,7 +1202,8 @@ export class AgentSession {
             messages: [{ role: "user", content: [{ type: "text", text: instruction }], timestamp: Date.now() }],
             tools: [NATIVE_TOOL_PROBE_READ_TOOL],
         }, { textToolCallProtocol: false, maxRetries: 0, temperature: 0, maxTokens: 768 });
-        return this._messageHasToolCallWithStringArgument(await stream.result(), "read", "path", path);
+        const message = await this._resolveProbeStreamCountingUsage(stream, "tool-probe", this._nextProbeUsageReportId(model, "read-task"));
+        return this._messageHasToolCallWithStringArgument(message, "read", "path", path);
     }
     async _runNativeEchoToolProbeTrial(model, token) {
         const instruction = `Native tool-call capability probe: echo-only. Use provider-native tool calling, not prose. ` +
@@ -1065,7 +1213,8 @@ export class AgentSession {
             messages: [{ role: "user", content: [{ type: "text", text: instruction }], timestamp: Date.now() }],
             tools: [TEXT_TOOL_PROTOCOL_ECHO_TOOL],
         }, { textToolCallProtocol: false, maxRetries: 0, temperature: 0, maxTokens: 256 });
-        return this._messageHasToolCallWithStringArgument(await stream.result(), "echo", "data", token);
+        const message = await this._resolveProbeStreamCountingUsage(stream, "tool-probe", this._nextProbeUsageReportId(model, "echo"));
+        return this._messageHasToolCallWithStringArgument(message, "echo", "data", token);
     }
     async _gradeNativeToolCallingForModel(model, token) {
         const path = join(getProcessWorkRun(this._agentDir, "probes", "native-tools").path, `pi-native-probe-${process.pid}-${Date.now()}.txt`);
@@ -1090,7 +1239,7 @@ export class AgentSession {
             temperature: 0,
             maxTokens: 256,
         });
-        const message = await stream.result();
+        const message = await this._resolveProbeStreamCountingUsage(stream, "text-protocol-calibration", this._nextProbeUsageReportId(model, `text-protocol:${variant}`));
         const text = message.content
             .filter((block) => block.type === "text")
             .map((block) => block.text)
@@ -1127,40 +1276,51 @@ export class AgentSession {
         }
         return { status: "failed", attemptedAt, variantsTried };
     }
+    /**
+     * A PURE READER of the persisted calibration — never calibrates inline and
+     * never throws out of the prompt path. A model whose flag is on but has no valid current-version
+     * protocol on record falls back to native for this turn (with a warning pointing at /toolprobe)
+     * instead of blocking the user's message behind up to 8 inline calibration completions or
+     * aborting the turn entirely. Calibration now only ever happens off the hot path: explicit
+     * /toolprobe, or the capability-gate spine's evidence-gated auto-probe.
+     */
     async _ensureTextToolProtocolForActiveModel() {
         const model = this.agent.state.model;
         if (!this._textProtocolFlag(model)) {
             this.agent.textToolCallProtocol = undefined;
             return;
         }
+        // Force-enable (a global settings override or Model.textToolCallProtocol) wins regardless of
+        // whether this model has ever been graded-probed — that is the point of an explicit override.
+        // Preserve it exactly as before: default to the tool-tag variant, no inline calibration. Only
+        // the graded-evidence path below (flag on solely because of a persisted toolProbe verdict)
+        // needs a valid persisted protocol to proceed.
+        const forceEnabled = this._toolRepairSettings().textProtocol === true || model?.textToolCallProtocol === true;
         const modelKey = this._modelAdaptationKeyFor(model);
-        if (!modelKey) {
+        if (!modelKey || forceEnabled) {
             this.agent.textToolCallProtocol = true;
             return;
         }
         const profile = this._modelAdaptationStore.get(modelKey);
-        if (profile.protocol?.version === TEXT_TOOL_PROTOCOL_VERSION) {
-            if (profile.protocol.status === "failed") {
-                this.agent.textToolCallProtocol = undefined;
-                throw new Error(`Previous text tool protocol calibration failed for ${modelKey} at ${profile.protocol.attemptedAt}. ` +
-                    `Variants tried: ${profile.protocol.variantsTried.join(", ")}. ` +
-                    `Run /toolhealth for details or /toolprotocol-reset ${modelKey} to retry calibration.`);
-            }
+        if (profile.protocol?.version === TEXT_TOOL_PROTOCOL_VERSION && profile.protocol.status !== "failed") {
             this.agent.textToolCallProtocol = { variant: profile.protocol.variant };
             return;
         }
-        const result = await this._calibrateTextToolProtocolForModel(model, modelKey, { persistFailure: true });
-        if (result.status === "calibrated") {
-            this.agent.textToolCallProtocol = { variant: result.variant };
-            return;
-        }
         this.agent.textToolCallProtocol = undefined;
-        throw new Error(`Model ${modelKey} cannot follow the text tool protocol after calibration. ` +
-            `Run /toolhealth for details or /toolprotocol-reset ${modelKey} to retry calibration.`);
+        this._emit({
+            type: "warning",
+            message: profile.protocol?.status === "failed"
+                ? `Text tool protocol calibration for ${modelKey} previously failed (variants tried: ${profile.protocol.variantsTried.join(", ")}); falling back to native tool calls this turn. Run /toolprobe ${modelKey} to recalibrate.`
+                : `Text tool protocol for ${modelKey} has no valid calibration on record; falling back to native tool calls this turn. Run /toolprobe ${modelKey} to calibrate.`,
+        });
     }
     _modelRef(model) {
         return `${model.provider}/${model.id}`;
     }
+    /** The persisted `/toolprobe` verdict on record for this model, if any (undefined = unprobed). */
+    _toolProbeVerdict(model) {
+        return this._modelAdaptationStore.get(this._modelRef(model)).toolProbe?.status;
+    }
     _formatToolProbeReport(results) {
         const lines = [
             "Tool probe results:",
@@ -1258,11 +1418,22 @@ export class AgentSession {
         }
         return { results, table: this._formatToolProbeReport(results) };
     }
+    /**
+     * The text-protocol circuit breaker. Every parse failure (from either the
+     * live per-completion {@link Agent.onTextToolProtocolParse} callback or the post-hoc detection in
+     * {@link _recordTextToolProtocolParseOutcomeFromLastAssistant}) gets a throttled one-line
+     * corrective steer for the next turn. On the 3rd consecutive SAME-SIGNATURE failure — graded
+     * evidence a model genuinely cannot speak this dialect, not a single bad turn — the breaker also
+     * demotes the persisted tool-probe verdict to "none" so {@link _textProtocolFlag} reads false next
+     * turn and native is attempted instead of thrashing on a protocol this model has proven it can't
+     * follow.
+     */
     _handleTextToolProtocolParse(event) {
         this._textProtocolParseObservedThisTurn = true;
         const modelKey = `${event.provider}/${event.model}`;
         if (event.status === "parsed")
             return;
+        this._maybeInjectTextProtocolCorrectiveSteer(event.variant);
         const signature = `${event.variant}:${event.reason ?? "failed"}`;
         const previous = this._textProtocolParseFailures.get(modelKey);
         const repeats = previous?.signature === signature ? previous.repeats + 1 : 1;
@@ -1275,6 +1446,43 @@ export class AgentSession {
             this.agent.textToolCallProtocol = undefined;
         }
         this._textProtocolParseFailures.delete(modelKey);
+        // Demote on graded evidence -- TEXT_TOOL_PROTOCOL_PARSE_FAILURE_THRESHOLD identical-signature
+        // parse failures in a row -- rather than thrashing every turn. The fresh probedAt doubles as
+        // the capability-gate spine's auto-probe freshness gate, so this demotion doesn't immediately
+        // trigger a re-probe/re-phone loop.
+        const probedAt = new Date().toISOString();
+        this._modelAdaptationStore.setToolProbe(modelKey, {
+            version: TEXT_TOOL_PROTOCOL_VERSION,
+            status: "none",
+            probedAt,
+            nativeGrade: profile.toolProbe?.nativeGrade,
+            diagnostic: `Text protocol parsing failed ${TEXT_TOOL_PROTOCOL_PARSE_FAILURE_THRESHOLD}x in a row with signature "${signature}".`,
+        }, probedAt);
+        this._emit({
+            type: "warning",
+            message: `Text tool protocol for ${modelKey} stopped parsing after ${TEXT_TOOL_PROTOCOL_PARSE_FAILURE_THRESHOLD} attempts; demoted to native fallback. Run /toolprobe ${modelKey} to recalibrate.`,
+        });
+    }
+    /**
+     * A phone model whose envelope fails to parse gets no corrective guidance today —
+     * the runaway-loop backstop only trips on repeated PARSED tool-call signatures (agent-loop.ts), so
+     * an every-turn unparseable-prose model never trips it. Inject a one-line reminder of the envelope
+     * shape as a nextTurn message, reusing {@link formatVariantEnvelope} so the reminder can never
+     * drift from the grammar the primer actually teaches. Throttled to the first failure this session
+     * and then every {@link TEXT_TOOL_PROTOCOL_STEER_INTERVAL}th after — the breaker above is what
+     * actually demotes a genuinely-failing model at the 3rd same-signature failure; this is guidance,
+     * not a second counter.
+     */
+    _maybeInjectTextProtocolCorrectiveSteer(variant) {
+        this._textProtocolCorrectiveSteerCount++;
+        if (this._textProtocolCorrectiveSteerCount !== 1 &&
+            this._textProtocolCorrectiveSteerCount % TEXT_TOOL_PROTOCOL_STEER_INTERVAL !== 0) {
+            return;
+        }
+        const reminder = `Reminder: to call a tool, emit exactly this envelope shape: ${formatVariantEnvelope(variant, "TOOL", '{"arg":"value"}')} — no other format is recognized. Reasoning may appear as prose before the envelope, never inside it.`;
+        this.sendCustomMessage({ customType: "text-protocol-corrective-steer", content: reminder, display: false }, { deliverAs: "nextTurn" }).catch(() => {
+            // Best-effort steer; a failure to queue it must not break parse-failure handling.
+        });
     }
     _handleTextToolProtocolValidationOutcome(event) {
         if (event.source !== "text-protocol")
@@ -1543,10 +1751,10 @@ export class AgentSession {
                 ...this._profileFilter.profileDeniedResourceObservations(),
                 ...this._profileFilter.getInertExtensionWarnings(),
                 ...this._unboundToolGrantWarnings,
-                // G7: auto-built per-turn foreground envelope (observe-only; not enforced). Falls back to a
+                // Auto-built per-turn foreground envelope (observe-only; not enforced). Falls back to a
                 // live preview when no turn has run yet so /context always shows the current scope.
                 formatForegroundEnvelopeObservation(this._currentForegroundEnvelope ?? this._buildForegroundEnvelopeFromState()),
-                // G14 (ratified): a user disable always beats a profile grant — surface the conflict.
+                // A user disable always beats a profile grant — surface the conflict.
                 ...["tools", "skills", "prompts", "extensions"].flatMap((kind) => this.settingsManager
                     .getProfileGrantsOverriddenByUserDisable(kind)
                     .map((entry) => `profile grants ${kind} "${entry}" but your disable list overrides it (user disable wins; re-enable to use)`)),
@@ -1558,7 +1766,10 @@ export class AgentSession {
         return formatContextCompositionDashboard(this.getContextCompositionReport());
     }
     formatToolRepairHealthReport() {
-        return formatToolRepairHealthReport(this._modelAdaptationStore, new Date(), this._toolRecoveryLogger.getStats());
+        return [
+            formatToolRepairHealthReport(this._modelAdaptationStore, new Date(), this._toolRecoveryLogger.getStats()),
+            formatToolSelectionReport(this._toolSelection.getReport()),
+        ].join("\n\n");
     }
     async flushToolRecoveryLogsForTests(timeoutMs = 1000) {
         await this._toolRecoveryLogger.flush(timeoutMs);
@@ -1625,6 +1836,119 @@ export class AgentSession {
     _installAgentToolHooks() {
         this.agent.beforeToolCall = this._toolGate.beforeToolCall;
         this.agent.afterToolCall = this._toolGate.afterToolCall;
+        this.agent.onRunawayStop = (info) => this._handleRunawayStop(info);
+        this.agent.onToolValidationEscalation = (event) => this._handleToolValidationEscalation(event);
+    }
+    /**
+     * The runaway-loop backstop ({@link Agent.maxStallTurns}) stopped a turn stuck repeating one
+     * identical tool-call signature. Previously silent — this is the first host handler. Records a
+     * session-log/telemetry entry (see {@link RUNAWAY_STOP_CUSTOM_TYPE}) and surfaces a user-visible
+     * warning through the same event the context-window/compaction backstops use.
+     */
+    _handleRunawayStop(info) {
+        const record = {
+            signature: info.signature,
+            repeats: info.repeats,
+            model: this.model?.id,
+            provider: this.model?.provider,
+            at: new Date().toISOString(),
+        };
+        this.sessionManager.appendCustomEntry(RUNAWAY_STOP_CUSTOM_TYPE, record);
+        this._emit({
+            type: "warning",
+            message: `Stopped: the model repeated the same tool call ${info.repeats} times in a row without making progress. Review the last tool result and steer or retry with a different approach.`,
+        });
+    }
+    /** Anti-loop: true when this model's persisted tool-probe verdict was written within the
+     * auto-probe freshness window ({@link AUTO_TOOL_PROBE_FRESHNESS_MS}) — covers a very recent
+     * explicit `/toolprobe` run or a fresh circuit-breaker demote from an EARLIER session, complementing
+     * the in-session {@link _autoProbedModels} latch. */
+    _hasFreshToolProbeVerdict(modelKey) {
+        const probedAt = this._modelAdaptationStore.get(modelKey).toolProbe?.probedAt;
+        if (!probedAt)
+            return false;
+        const age = Date.now() - new Date(probedAt).getTime();
+        return Number.isFinite(age) && age >= 0 && age < AUTO_TOOL_PROBE_FRESHNESS_MS;
+    }
+    /**
+     * Evidence-gated native→phone auto-probe for a LOCAL/MANAGED model (never cloud — see
+     * {@link isLocalOrManagedRouterModel}) that just crossed the tool-argument-validation escalation
+     * threshold — repeated identical validation failures with no successful native call in between,
+     * which is exactly the graded evidence {@link Agent.onToolValidationEscalation} already requires
+     * before firing. Runs the SAME probe `/toolprobe` uses ({@link _probeToolCallingForModel}: native
+     * trials first, so a model that can actually tool-call natively still resolves to verdict
+     * "native" and is never phoned) entirely OFF the hot path — fired here but never awaited by the
+     * caller, so a slow or failing probe can never block or throw the user's in-flight turn.
+     * Anti-loop: skipped when this session already auto-probed this model, or a fresh persisted
+     * verdict already exists ({@link _hasFreshToolProbeVerdict}) — otherwise a model that keeps
+     * failing validation every turn would re-fire the (multi-completion) probe every single turn.
+     */
+    _maybeAutoProbeOnValidationEscalation(model) {
+        const modelKey = this._modelRef(model);
+        if (this._autoProbedModels.has(modelKey) || this._hasFreshToolProbeVerdict(modelKey))
+            return;
+        this._autoProbedModels.add(modelKey);
+        void this._probeToolCallingForModel(model)
+            .then((result) => {
+            if (this._disposed)
+                return;
+            const detail = result.verdict === "text-protocol"
+                ? ` (variant ${result.variant}); it will use the text tool protocol starting next turn`
+                : result.verdict === "none"
+                    ? " — no working tool-call path was found; run /toolprobe for details"
+                    : "; native tool calls stay in use";
+            this._emit({
+                type: "warning",
+                message: `Auto-probed ${modelKey} after repeated native tool-call validation failures: verdict "${result.verdict}"${detail}.`,
+            });
+        })
+            .catch((error) => {
+            if (this._disposed)
+                return;
+            this._emit({
+                type: "warning",
+                message: `Auto-probe for ${modelKey} (triggered by repeated tool-call validation failures) did not complete: ${error instanceof Error ? error.message : String(error)}.`,
+            });
+        });
+    }
+    /**
+     * A repeated identical tool-argument-validation failure crossed the escalation threshold
+     * ({@link Agent.toolValidationEscalationThreshold}) — the graded evidence the capability-gate
+     * spine acts on. Always records a session-log/telemetry entry (see {@link
+     * TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE}), then branches on the failing model's class:
+     * - LOCAL/MANAGED ({@link isLocalOrManagedRouterModel}, never cloud): the failure is evidence the
+     *   model may lack native tool-calling, so it fires the evidence-gated native→phone auto-probe
+     *   off the hot path ({@link _maybeAutoProbeOnValidationEscalation}). Escalating a local model's
+     *   ROUTER TIER on a tool-call failure would not fix a capability problem, so this branch never
+     *   touches the model router.
+     * - CLOUD (known tool-capable): the failure is evidence the routed tier is too weak for this
+     *   request, so it escalates via {@link ModelRouterController.requestValidationFailureEscalation}
+     *   — de-conflated from the beforeToolCall mutation gate ({@link
+     *   ModelRouterController.maybeEscalateToolCall}/`shouldEscalateModelRouterTool`): repeated
+     *   validation failure is grounds to escalate REGARDLESS of the failing tool's mutation status,
+     *   so a read-only tool's repeated failure now escalates too (previously a no-op, since the old
+     *   code reused the mutation gate verbatim for this unrelated signal). Cloud models are never
+     *   probe-gated or phoned by this handler.
+     * If the registry can no longer resolve `event.model`/`event.provider` (e.g. the model was
+     * unregistered mid-session), falls back to the cloud/tier-escalation path — the previously
+     * existing behavior — rather than silently dropping the signal.
+     */
+    _handleToolValidationEscalation(event) {
+        const record = {
+            tool: event.tool,
+            signature: event.signature,
+            repeats: event.repeats,
+            model: event.model,
+            provider: event.provider,
+            at: new Date().toISOString(),
+        };
+        this.sessionManager.appendCustomEntry(TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE, record);
+        const model = this._modelRegistry.find(event.provider, event.model);
+        if (model && isLocalOrManagedRouterModel(model)) {
+            this._maybeAutoProbeOnValidationEscalation(model);
+            return;
+        }
+        this._modelRouter.requestValidationFailureEscalation();
     }
     // =========================================================================
     // Event Subscription
@@ -1970,18 +2294,19 @@ export class AgentSession {
             this.abortCompaction();
             this.abortBranchSummary();
             this.abortBash();
+            disposePersistentShellSession(this._shellSessionKey);
             this._cancelPrefixWarm();
             this.agent.abort();
-            // R8: stop any deployment-registered gateway channels / schedulers.
+            // Stop any deployment-registered gateway channels / schedulers.
             void this._gatewayRegistry.stop().catch(() => { });
-            // Bug #21: abort any in-flight background reflection so it cannot keep spending tokens or
+            // Abort any in-flight background reflection so it cannot keep spending tokens or
             // write memory/skills against this now-disposed session.
             this._disposed = true;
             this._reflectionAbort.abort();
             // Abort any in-flight research pass or delegated worker for the same reason: a disposed
             // session must not keep spending tokens or persist evidence against dead state.
             this._backgroundLanes.abortInFlightLanes();
-            // Bug #20: clear the hooks this session installed on the shared agent so their closures stop
+            // Clear the hooks this session installed on the shared agent so their closures stop
             // pinning this (deactivated) session — and all its history/maps — in memory if the agent
             // instance outlives the session.
             this.agent.afterToolCall = undefined;
@@ -1994,7 +2319,7 @@ export class AgentSession {
         this._disconnectFromAgent();
         this._eventListeners = [];
         // Best-effort memory cleanup (release locks/handles). Write-side onSessionEnd is wired on a
-        // true session-end hook (P3); file-store shutdown is a no-op.
+        // true session-end hook; file-store shutdown is a no-op.
         void this._memory
             .getMemoryManager()
             .shutdownAll()
@@ -2049,7 +2374,7 @@ export class AgentSession {
     getActiveToolNames() {
         return this.agent.state.tools.map((t) => t.name);
     }
-    /** G7: build a foreground {@link CapabilityEnvelope} from the live session state (active tools, cwd, cost ceiling). */
+    /** Build a foreground {@link CapabilityEnvelope} from the live session state (active tools, cwd, cost ceiling). */
     _buildForegroundEnvelopeFromState() {
         return buildForegroundEnvelope({
             turnIndex: this._turnIndex,
@@ -2059,7 +2384,7 @@ export class AgentSession {
         });
     }
     /**
-     * G7: (re)build the foreground envelope for the current turn. Visibility only -- the foreground
+     * (Re)build the foreground envelope for the current turn. Visibility only -- the foreground
      * envelope is NOT enforced this round. Best-effort: never throws into the turn.
      */
     _refreshForegroundEnvelope() {
@@ -2070,7 +2395,7 @@ export class AgentSession {
             // Visibility only: a failure to build the envelope must never disturb the turn.
         }
     }
-    /** G7: the auto-constructed foreground envelope for the current/most-recent turn (visibility only). */
+    /** The auto-constructed foreground envelope for the current/most-recent turn (visibility only). */
     getForegroundEnvelope() {
         return this._currentForegroundEnvelope;
     }
@@ -2199,7 +2524,7 @@ export class AgentSession {
     }
     /**
      * Build a system prompt for a specific tool surface WITHOUT touching the session's base prompt
-     * state (G4 router-swap; see {@link SystemPromptBuilder.buildSystemPromptForToolNames}).
+     * state (used by the router's model swap; see {@link SystemPromptBuilder.buildSystemPromptForToolNames}).
      */
     _buildSystemPromptForToolNames(toolNames) {
         return this._systemPromptBuilder.buildSystemPromptForToolNames(toolNames);
@@ -2236,6 +2561,12 @@ export class AgentSession {
     getTransformersRuntime(modelId, baseUrl) {
         return this._localRuntimeController.getTransformersRuntime(modelId, baseUrl);
     }
+    /** Shared {@link PrismLlamaCppRuntime} for pi's own managed prism install — see
+     * {@link LocalRuntimeController.getPrismLlamaCppRuntime}. Delegates so `/models` and the
+     * readiness gate share the SAME cached instance, same contract as getLocalRuntime above. */
+    getPrismLlamaCppRuntime() {
+        return this._localRuntimeController.getPrismLlamaCppRuntime();
+    }
     /** models.json registers a local model's baseUrl as `<server>/v1` (OpenAI-compat); the runtime's
      * own health/boot endpoints are on the Ollama-native server root. Delegates to
      * {@link LocalRuntimeController}; kept here for `_warnIfManualModelChoiceIsRisky`'s own use. */
@@ -2250,6 +2581,27 @@ export class AgentSession {
     async _ensureRouteModelReady(resolved) {
         return this._localRuntimeController.ensureRouteModelReady(resolved);
     }
+    /**
+     * Every local model the CURRENT (post-reload) configuration could still route a turn to —
+     * the foreground model plus any router tier (cheap/medium/expensive) that still resolves to a
+     * real, authed, non-exhausted model. Fed to {@link LocalRuntimeController.reconcile} via the
+     * `reconcileLocalRuntimes` hook above, ONLY after a reload generation has fully committed, so a
+     * local model dropped from the live configuration has its pi-spawned runtime stopped instead of
+     * leaking a child process, while one still referenced here is left untouched. Read-only — never
+     * used for routing itself.
+     */
+    _collectEligibleLocalModelsForReconcile() {
+        const models = [];
+        const foregroundModel = this.agent.state.model;
+        if (foregroundModel)
+            models.push(foregroundModel);
+        for (const tier of ["cheap", "medium", "expensive"]) {
+            const resolved = this._modelRouter.resolveConfiguredTierModel(tier);
+            if (resolved)
+                models.push(resolved);
+        }
+        return models;
+    }
     getModelRouterStatus(formatLabel) {
         return this._modelRouter.getStatus(formatLabel);
     }
@@ -2310,6 +2662,10 @@ export class AgentSession {
         return this._promptUnserialized(text, options);
     }
     async _promptUnserialized(text, options) {
+        // Start of a new foreground prompt cycle -- rebaseline the cost guard's background-spend
+        // window so a PRIOR turn's background/spawned spend doesn't keep this turn's guard permanently
+        // tripped. Every round trip within this same turn (tool-call iterations) shares this baseline.
+        this._costGuardTurnBaselineUsd = this.getSpawnedUsage().cost;
         this._applyToolRepairLayerSettings();
         this._cancelPrefixWarm();
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
@@ -2322,7 +2678,7 @@ export class AgentSession {
         // selected/authenticated — can un-register it from _earlyDisplayedUserMessages instead of
         // leaking the reference forever.
         let userMessage;
-        // R4 effectiveness feedback: remember the recall page + the query so we can score, after the
+        // Effectiveness feedback: remember the recall page + the query so we can score, after the
         // response, whether the agent actually used the recalled context.
         let injectedRecall = "";
         let recallQuery = "";
@@ -2445,7 +2801,7 @@ export class AgentSession {
             }
             // Build messages array (recall page, then custom message if any, then user message)
             messages = [];
-            // R3: cross-session similarity recall. For a substantive turn, ask the memory providers to
+            // Cross-session similarity recall. For a substantive turn, ask the memory providers to
             // prefetch a relevant <memory_context> page from past sessions and prepend it as data ahead of
             // the user message. Best-effort and gated: trivial turns are skipped, and providers return ""
             // (no page) when nothing is relevant — so it stays net-negative and the GC packs stale pages.
@@ -2457,8 +2813,8 @@ export class AgentSession {
                         recallQuery = expandedText;
                         // Inject as a GC-managed custom context message (role "custom", customType
                         // "memory_context"), NOT a persisted user message: the semantic-memory context-GC packs
-                        // stale recall pages so they don't accumulate forever (Bug #7), and the transcript index
-                        // only re-reads user/assistant text so recalled snippets can't recirculate (Bug #10).
+                        // stale recall pages so they don't accumulate forever, and the transcript index
+                        // only re-reads user/assistant text so recalled snippets can't recirculate.
                         messages.push(createCustomMessage("memory_context", recall, false, undefined, new Date().toISOString()));
                     }
                 }
@@ -2528,7 +2884,7 @@ export class AgentSession {
         this._textProtocolValidationOutcomeThisTurn = undefined;
         await this._modelRouter.runRoutedTurn(messages, routedTurnModel, routedTurnRouteDecision);
         this._recordTextToolProtocolParseOutcomeFromLastAssistant();
-        // R4: score whether the agent actually used the recalled context, so the recall gate can adapt.
+        // Score whether the agent actually used the recalled context, so the recall gate can adapt.
         if (injectedRecall) {
             const response = this._findLastAssistantMessage();
             const responseText = response
@@ -2968,8 +3324,12 @@ export class AgentSession {
                 getBaseKeepRecentTokens: () => settings.keepRecentTokens,
                 resolveModelAndAuth: async (modelTier) => {
                     const model = modelTier === "cheap" ? selectedCompactionModel : sessionModel;
-                    const { apiKey, headers } = await this._resolveCompactionModelAndAuth(model, sessionModel);
-                    return { model, apiKey, headers };
+                    // Return the resolution result AS-IS: it may have fallen back to a different model
+                    // (e.g. session model, when the tier's model failed auth or the readiness gate),
+                    // and `failure` must reach the retry loop's auth-failed escalation rather than be
+                    // dropped — dropping it would pair the wrong model with the fallback's credentials
+                    // and silently skip the loop's visible failure/escalation handling.
+                    return this._resolveCompactionModelAndAuth(model, sessionModel);
                 },
                 summarizeAndVerify: async (params, model, apiKey, headers, branch) => {
                     const preparation = prepareCompaction(branch, {
@@ -3548,6 +3908,9 @@ export class AgentSession {
             reportSpawnedUsage: (usage, opts) => {
                 this.addSpawnedUsage(usage, opts);
             },
+            reportManagedLane: (event) => {
+                this._backgroundLanes.recordManagedLane(event);
+            },
         }, {
             getModel: () => this.model,
             isIdle: () => !this.isStreaming,
@@ -3608,15 +3971,15 @@ export class AgentSession {
     registerContextMemoryProvider(provider) {
         this._memory.registerContextMemoryProvider(provider);
     }
-    /** R8: the gateway/scheduler registry. A deployment runner registers providers and drives start/stop. */
+    /** The gateway/scheduler registry. A deployment runner registers providers and drives start/stop. */
     get gateways() {
         return this._gatewayRegistry;
     }
-    /** R8: register a deployment-supplied transport channel (gateway). */
+    /** Register a deployment-supplied transport channel (gateway). */
     registerChannelProvider(provider) {
         this._gatewayRegistry.registerChannel(provider);
     }
-    /** R8: register a deployment-supplied job scheduler (cron). */
+    /** Register a deployment-supplied job scheduler (cron). */
     registerJobScheduler(provider) {
         this._gatewayRegistry.registerScheduler(provider);
     }
@@ -3775,7 +4138,32 @@ export class AgentSession {
      * Retrieve the latest valid goal state snapshot from the session log.
      */
     getGoalStateSnapshot() {
-        return getLatestGoalStateSnapshot(this.sessionManager.getEntries());
+        return getLatestGoalStateSnapshot(this.sessionManager);
+    }
+    /**
+     * Persist one submitted continuation pass's turn/wall-clock/spend contribution onto the active
+     * goal's durable cumulative budget (see `GoalState.continuationTurnsUsed` et al.). This is the
+     * "persistence dep" `GoalLoopController` calls once per pass actually submitted — it, not the
+     * loop controller, is where USD gets attributed: it reads the session's OWN cumulative model
+     * spend (`getCostSummary().ownCost` — deliberately excludes worker/subagent spend, which is
+     * tracked and budgeted separately) and threads that single absolute reading into a
+     * `record_continuation_budget` event; the pure reducer in `goal-state.ts` derives the delta.
+     * A no-op when no goal state exists (defensive — in practice this is only ever called right
+     * after a pass the loop already confirmed was submitted against an active goal).
+     */
+    recordGoalContinuationPass(pass) {
+        const state = this.getGoalStateSnapshot();
+        if (!state)
+            return;
+        const sessionCostUsd = this.getCostSummary().ownCost;
+        const updated = applyGoalEvent(state, {
+            type: "record_continuation_budget",
+            turns: pass.turns,
+            wallClockMs: pass.wallClockMs,
+            sessionCostUsd,
+            now: new Date().toISOString(),
+        });
+        this.saveGoalStateSnapshot(updated);
     }
     /** Save native task-step state to the active session log. */
     saveTaskStepsStateSnapshot(state) {
@@ -3783,7 +4171,7 @@ export class AgentSession {
     }
     /** Retrieve the latest valid native task-step state from the active session log. */
     getTaskStepsStateSnapshot() {
-        return getLatestTaskStepsStateSnapshot(this.sessionManager.getEntries());
+        return getLatestTaskStepsStateSnapshot(this.sessionManager);
     }
     /**
      * Save a snapshot of the evidence bundle to the session log.
@@ -3806,7 +4194,7 @@ export class AgentSession {
     getLaneRecords() {
         return this._backgroundLanes.getLaneRecords();
     }
-    // G3/G8 autonomy telemetry + gate-outcome history live in AutonomyTelemetry (see
+    // Autonomy telemetry + gate-outcome history live in AutonomyTelemetry (see
     // autonomy-telemetry.ts). These stubs keep the god file's internal call surface stable while the
     // sink logic and the owned gate-outcome fields live there.
     _emitAutonomyTelemetry(event) {
@@ -3815,7 +4203,7 @@ export class AgentSession {
     _recordGateOutcome(outcome) {
         this._autonomyTelemetry.recordGateOutcome(outcome);
     }
-    /** G8: copies of the bounded gate-outcome history, oldest first, latest last. */
+    /** Copies of the bounded gate-outcome history, oldest first, latest last. */
     getGateOutcomeHistory() {
         return this._autonomyTelemetry.getGateOutcomeHistory();
     }
@@ -3831,10 +4219,18 @@ export class AgentSession {
     getLearningDecisionSnapshots() {
         return getLearningDecisionSnapshots(this.sessionManager.getEntries());
     }
+    /**
+     * The single injection point that makes the goal-continuation snapshot lane-aware:
+     * `laneRecords` feeds BOTH `evaluateGoalContinuation`'s "waiting" branch (a worker dispatched
+     * against an open requirement) and the per-goal worker-spend overlay — read fresh here so BOTH the
+     * goal loop (`GoalLoopController`) and the idle scheduler (`BackgroundLaneController`) see the
+     * same live lane state, since both reach this same method.
+     */
     getGoalRuntimeSnapshot(settings) {
         return buildGoalRuntimeSnapshot({
-            entries: this.sessionManager.getEntries(),
+            sessionManager: this.sessionManager,
             settings,
+            laneRecords: this._backgroundLanes.getLaneRecords(),
         });
     }
     /**
@@ -3847,6 +4243,25 @@ export class AgentSession {
             mode: this.settingsManager.getModelCapabilitySettings().mode,
         });
     }
+    /**
+     * Whether the CURRENT session model may drive a worktree-sync lane worker (see
+     * `evaluateLaneWorkerRefusal` in model-capability.ts): full capability class, a DECLARED
+     * (registry) context window, an ADVERTISED native tool-call path (`Model.textToolCallProtocol`
+     * unset/false -- `true` means phone-only), and no graded `/toolprobe` demotion to
+     * "text-protocol"/"none" on record. An unprobed model (no verdict on record yet) is eligible on
+     * its advertised support alone. `undefined` means eligible.
+     */
+    getLaneWorkerRefusal() {
+        const profile = this.getModelCapabilityProfile();
+        const model = this.model;
+        const verdict = model ? this._toolProbeVerdict(model) : undefined;
+        return evaluateLaneWorkerRefusal({
+            capabilityClass: profile.class,
+            contextWindow: profile.contextWindow,
+            toolCallingAdvertised: model?.textToolCallProtocol !== true,
+            toolCallingDemoted: verdict === "text-protocol" || verdict === "none",
+        });
+    }
     /**
      * Run one bounded, read-only research pass and persist its results. Delegates to
      * {@link BackgroundLaneController}; see there for the full gating/budget/dedupe contract.
@@ -3875,8 +4290,15 @@ export class AgentSession {
     async continueGoalOnce(options) {
         return this._goalContinuation.continueGoalOnce(options);
     }
+    /**
+     * Public entry point for BOTH idle autosteer and manual (`/goal start`, `/goal-continue`)
+     * continuation. Delegates to {@link BackgroundLaneController.continueGoalLoopExclusive}, the
+     * single-flight guard that prevents two goal loops from racing to submit prompts through the
+     * same session (which throws "Agent is already processing" from the second submission). Do not
+     * call `this._goalContinuation.continueGoalLoop` directly from here — that bypasses the guard.
+     */
     async continueGoalLoop(options) {
-        return this._goalContinuation.continueGoalLoop(options);
+        return this._backgroundLanes.continueGoalLoopExclusive(options);
     }
     /**
      * Run a one-shot LLM completion fully ISOLATED from the main session — the load-bearing primitive
@@ -3886,7 +4308,7 @@ export class AgentSession {
         return this._reflection.runIsolatedCompletion(opts);
     }
     /**
-     * Native end-of-loop reflection pass (R2). Delegates to {@link ReflectionController}; returns null
+     * Native end-of-loop reflection pass. Delegates to {@link ReflectionController}; returns null
      * when the demand gate skips or in a child session.
      */
     async runReflectionPass(input) {