open-multi-agent-kit 0.96.0 → 0.96.2

package/dist/core/agent-session.js

@@ -16,7 +16,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join as joinPath } from "node:path";
 import { isDeepStrictEqual } from "node:util";
-import { getVisionRouteModel, isVisionRouteModel } from "omk-agent-core";
+import { getVisionRouteModel } from "omk-agent-core";
 import { clampThinkingLevel, cleanupSessionResources, deriveContextPromptCacheKey, getSupportedThinkingLevels, isContextOverflow, modelsAreEqual, resetApiProviders, streamSimple, } from "omk-ai";
 import { APP_NAME, VERSION } from "../config.js";
 import { theme } from "../modes/interactive/theme/theme.js";
@@ -32,6 +32,7 @@ import { getCompactionHeadroomThreshold } from "./compaction/compaction.js";
 import { createCompactionHysteresisConfig, createCompactionHysteresisState, stepCompactionHysteresis, } from "./compaction/hysteresis.js";
 import { calculateContextTokens, collectEntriesForBranchSummary, compact, estimateContextTokens, estimateProjectedContextTokens, generateBranchSummary, prepareCompaction, resolveCompactionModel, } from "./compaction/index.js";
 import { compactionEmitWillRetry } from "./compaction/resume-policy.js";
+import { isSessionModelOverflow, shouldSkipCompactionCheck } from "./compaction-gate.js";
 import { estimateToolResultReserve, } from "./context-budget-reserved-tokens.js";
 import { createDiskContextBudgetCacheProviderV2, DiskContextBudgetCacheProviderV2, } from "./context-budget-v2-cache-disk.js";
 import { applyContextCacheInvalidation, createContextCacheInvalidationSnapshot, } from "./context-budget-v2-cache-invalidation.js";
@@ -43,6 +44,7 @@ import { ExtensionRunner, wrapRegisteredTools, } from "./extensions/index.js";
 import { emitSessionShutdownEvent } from "./extensions/runner.js";
 import { assertTextChatModelForCompletion } from "./grok-harness.js";
 import { grokPlaybookAppendForProvider } from "./grok-playbook.js";
+import { captureHostResourceSnapshot } from "./host-resource-snapshot.js";
 import { decideLoadoutAccess } from "./loadout-access-policy.js";
 import { loadMcpServerConfigs } from "./mcp/config.js";
 import { McpManager } from "./mcp/manager.js";
@@ -52,6 +54,7 @@ import { TurnMetricsSink } from "./turn-metrics.js";
 const DISABLED_ENV_VALUES = new Set(["0", "false", "off", "disable", "disabled"]);
 const MAX_OVERFLOW_RECOVERY_ATTEMPTS = 2;
 const OVERFLOW_RECOVERY_EMERGENCY_TOKENS = 4_096;
+const MAX_RESOURCE_OBSERVATION_JOURNALS = 32;
 function isDisabledEnvValue(value) {
     return value !== undefined && DISABLED_ENV_VALUES.has(value.trim().toLowerCase());
 }
@@ -70,20 +73,31 @@ function firstTextContent(result) {
     return undefined;
 }
 import { redactCredentialShapedContent } from "./compaction/transaction.js";
+import { selectContextFilesForModel } from "./model-prompt-policy.js";
 import { findExactModelReferenceMatch } from "./model-resolver.js";
+import { computePromptTokenBudget } from "./prompt-budget.js";
+import { classifyPromptCacheTransition } from "./prompt-cache.js";
+import { createPromptSettlementState, reducePromptSettlement, settlePromptIfReady, } from "./prompt-settlement.js";
 import { expandPromptTemplate } from "./prompt-templates.js";
-import { isContentSafetyStopMessage, isQuotaExhaustionMessage, isStickySafetyModel, isTransientProviderErrorMessage, pickFailoverCandidate, resolveProviderResilience, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { isQuotaExhaustionMessage, isStickySafetyModel, pickFailoverCandidate, resolveProviderResilience, shouldEjectStickySafetyModel, shouldHonorSafetyFailover, stickySafetyBlockMessage, } from "./provider-resilience.js";
+import { computeRetryDelayMs, failoverModelKey, isFailoverTriggerError, isRetryableAssistantError, nextRetryAttempt, retryBudgetForAssistantError, } from "./provider-retry.js";
 import { getBiasStepsForCell, parseRouterBiasSnapshot } from "./reasoning-router-bias.js";
 import { classifyTaskV4, deriveRouterFeedbackFeaturesV4, resolveThinkingLevelV4WithUncertainty, TASK_CLASS_THINKING_LEVELS_V4, } from "./reasoning-router-v4.js";
 import { redactSensitiveText, redactSensitiveTextForced } from "./redaction.js";
 import { getRepositoryRouterLearningPaths } from "./repository-learning-scope.js";
+import { decideResourceAdmission } from "./resource-admission.js";
+import { resolveResourceGovernorSettings } from "./resource-governor-settings.js";
+import { admissionObservationFacts, classificationObservationFacts, ResourceObservationJournal, settledObservationFacts, snapshotObservationFacts, soundObservationFacts, } from "./resource-observation-journal.js";
+import { decideResourceSafetyGate, RESOURCE_PRESSURE_REQUIRED_ACTION } from "./resource-safety-gate.js";
 import { appendRouterFeedbackRecord, ROUTER_FEEDBACK_LEVELS, } from "./router-feedback-collector.js";
 import { RunJournalStore } from "./run-journal-store.js";
+import { RunResourceLeaseController } from "./run-resource-lease.js";
 import { SessionBashRuntime } from "./session-bash-runtime.js";
 import { SessionBashService } from "./session-bash-service.js";
 import { SessionCompactionService } from "./session-compaction-service.js";
 import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-manager.js";
 import { acquireSessionOwnerLeaseSync } from "./session-owner-lease.js";
+import { assembleSessionSystemPrompt } from "./session-system-prompt.js";
 import { classifySessionTermination, } from "./session-termination.js";
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPromptPlan } from "./system-prompt.js";
@@ -92,6 +106,8 @@ import { createAllToolDefinitions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { createVerifiedBashOperations } from "./verified-bash-adapter.js";
 import { resolveSessionWorkspaceScope } from "./verified-bash-runtime.js";
+import { classifyWorkloadCommand } from "./workload-classifier.js";
+import { WorkloadPermitError, WorkloadPermitPool } from "./workload-permit-pool.js";
 /**
  * Parse a skill block from message text.
  * Returns null if the text doesn't contain a skill block.
@@ -315,6 +331,8 @@ export class AgentSession {
     // v10.3-Ω: models that already refused/failed this turn — failover must advance,
     // not re-pick the same candidate (claude-opus-5 → grok → grok → grok loop fix).
     _refusedModels = new Set();
+    /** True when `--model` / `--provider` pinned this process to one model. */
+    _modelPinned;
     // Bash execution state
     _bashService;
     _compactionService;
@@ -348,6 +366,14 @@ export class AgentSession {
     _runJournalStore;
     _ownedSessionOwnerLease;
     _activeRunId = null;
+    // Resource governor (roadmap M2): lease controller owns the temporary tool
+    // cap for governed runs; the last decision backs the §19.4 read-only API.
+    _resourceLeaseController;
+    _resourceObservations = null;
+    _resourceObservationJournals = new Map();
+    _latestResourcePromptRunId = null;
+    _lastResourceAdmission = null;
+    _workloadPermitPool;
     _pendingRuntimeTerminationCause;
     _activeRunToolTermination;
     _lastTermination;
@@ -383,6 +409,7 @@ export class AgentSession {
         this.sessionManager = config.sessionManager;
         this.settingsManager = config.settingsManager;
         this._scopedModels = config.scopedModels ?? [];
+        this._modelPinned = config.modelPinned === true;
         this._resourceLoader = config.resourceLoader;
         this._customTools = config.customTools ?? [];
         this._cwd = config.cwd;
@@ -427,6 +454,7 @@ export class AgentSession {
             isStreaming: () => this.isStreaming,
             pushMessage: (message) => this.agent.state.messages.push(message),
             appendMessage: (message) => this.sessionManager.appendMessage(message),
+            acquireResourcePermit: (command, signal) => this._acquireBashResourcePermit(command, signal),
         });
         this._compactionService = new SessionCompactionService({
             sessionManager: this.sessionManager,
@@ -1043,13 +1071,14 @@ export class AgentSession {
     };
     _willRetryAfterAgentEnd(event) {
         const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled || this._retryAttempt >= settings.maxRetries) {
+        if (!settings.enabled)
             return false;
-        }
         for (let i = event.messages.length - 1; i >= 0; i--) {
             const message = event.messages[i];
             if (message.role === "assistant") {
-                return this._isRetryableError(message);
+                const assistant = message;
+                const maxRetries = retryBudgetForAssistantError(assistant, settings.maxRetries);
+                return this._retryAttempt < maxRetries && this._isRetryableError(assistant);
             }
         }
         return false;
@@ -1554,7 +1583,7 @@ export class AgentSession {
         }
         return undefined;
     }
-    _getContextBudgetOptions(queryContext = this._extractCurrentQuery()) {
+    _getContextBudgetOptions(queryContext = this._extractCurrentQuery(), model = this.model) {
         const contextGovernorOverride = process.env.OMK_CONTEXT_GOVERNOR;
         if (contextGovernorOverride === "0") {
             return undefined;
@@ -1562,56 +1591,24 @@ export class AgentSession {
         if (contextGovernorOverride !== "1" && !this.settingsManager.getContextBudgetEnabled()) {
             return undefined;
         }
-        const contextWindow = this.model?.contextWindow ?? 0;
-        // --- maxPromptTokens ---
-        // Priority 1: explicit env override (user knows best)
-        const envMaxPrompt = parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_MAX_PROMPT_TOKENS");
-        let maxPromptTokens;
-        let responseReserveTokens;
-        if (envMaxPrompt !== undefined) {
-            // User override — use as-is for prompt, derive response reserve normally
-            maxPromptTokens = envMaxPrompt;
-            responseReserveTokens =
-                parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ??
-                    this._computeResponseReserve(contextWindow);
-        }
-        else if (contextWindow > 0) {
-            // Dynamic: derive from model contextWindow
-            const envPromptRatio = parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_PROMPT_RATIO");
-            const envResponseRatio = parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RATIO");
-            responseReserveTokens =
-                parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ??
-                    this._computeResponseReserve(contextWindow, envResponseRatio);
-            const safetyMargin = Math.floor(contextWindow * SAFETY_MARGIN_RATIO);
-            if (envPromptRatio !== undefined && envPromptRatio > 0 && envPromptRatio < 1) {
-                maxPromptTokens = Math.floor(contextWindow * envPromptRatio);
-            }
-            else {
-                // Default: contextWindow minus reserves and safety margin
-                maxPromptTokens = contextWindow - responseReserveTokens - safetyMargin;
-            }
-        }
-        else {
-            // No model info — legacy fallback
-            maxPromptTokens = LEGACY_MAX_PROMPT_TOKENS;
-            responseReserveTokens =
-                parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS") ?? LEGACY_RESPONSE_RESERVE_TOKENS;
-        }
+        const contextWindow = model?.contextWindow ?? 0;
+        const budget = computePromptTokenBudget({
+            contextWindow,
+            modelMaxTokens: model?.maxTokens,
+            envMaxPromptTokens: parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_MAX_PROMPT_TOKENS"),
+            envResponseReserveTokens: parsePositiveIntegerEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RESERVE_TOKENS"),
+            envPromptRatio: parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_PROMPT_RATIO"),
+            envResponseRatio: parsePositiveFloatEnv("OMK_CONTEXT_GOVERNOR_RESPONSE_RATIO"),
+        });
+        const maxPromptTokens = budget.maxPromptTokens;
+        const responseReserveTokens = budget.responseReserveTokens;
         const cacheProvider = this._contextBudgetCacheProvider ?? this._createContextBudgetCacheProvider();
         cacheProvider.setInvalidationSnapshot?.(this._contextCacheInvalidationSnapshot);
         this._contextBudgetCacheProvider = cacheProvider;
-        // Enforce floor
-        if (maxPromptTokens < MIN_PROMPT_TOKENS) {
-            maxPromptTokens = MIN_PROMPT_TOKENS;
-        }
-        // Ensure responseReserve does not exceed maxPromptTokens
-        if (responseReserveTokens >= maxPromptTokens) {
-            responseReserveTokens = Math.max(Math.floor(maxPromptTokens / 4), LEGACY_RESPONSE_RESERVE_TOKENS);
-        }
         return {
             maxPromptTokens,
             responseReserveTokens,
-            modelId: this.model?.id ?? "unknown",
+            modelId: model?.id ?? "unknown",
             tokenizerMode: parseTokenizerModeEnv(process.env.OMK_CONTEXT_GOVERNOR_TOKENIZER),
             activeSkillNames: parseCommaSeparatedEnv(process.env.OMK_CONTEXT_GOVERNOR_ACTIVE_SKILLS),
             queryContext,
@@ -1622,15 +1619,6 @@ export class AgentSession {
      * Compute responseReserveTokens from contextWindow.
      * Prefers the model's own maxTokens when available, otherwise uses a ratio.
      */
-    _computeResponseReserve(contextWindow, overrideRatio) {
-        // Prefer model's maxTokens (actual output limit) if available and reasonable
-        const modelMaxTokens = this.model?.maxTokens;
-        if (modelMaxTokens !== undefined && modelMaxTokens > 0 && modelMaxTokens < contextWindow) {
-            return modelMaxTokens;
-        }
-        const ratio = overrideRatio ?? RESPONSE_RESERVE_RATIO;
-        return Math.max(Math.floor(contextWindow * ratio), LEGACY_RESPONSE_RESERVE_TOKENS);
-    }
     _recordPromptCachePlan(reason) {
         const boundary = this.agent.state.systemPromptCacheBoundary;
         const scope = this.model ? `${this.model.provider}/${this.model.id}` : "unknown";
@@ -1641,65 +1629,64 @@ export class AgentSession {
             messages: [],
             tools: this.agent.state.tools,
         }, scope);
-        if (!nextKey) {
+        const transition = classifyPromptCacheTransition(this._promptCacheKey, nextKey);
+        if (transition.kind === "bypass") {
             this._promptCacheBoundaryBypasses += 1;
             this._promptCacheStablePrefixCharacters = 0;
-            if (this._promptCacheKey !== undefined) {
+            if (transition.recordBreak) {
                 this._promptCacheLastBreakReason = reason;
             }
             this._promptCacheKey = undefined;
             return;
         }
-        if (this._promptCacheKey !== undefined && this._promptCacheKey !== nextKey) {
+        if (transition.kind === "changed") {
             this._promptCacheKeyChanges += 1;
             this._promptCacheLastBreakReason = reason;
         }
         this._promptCacheKey = nextKey;
         this._promptCacheStablePrefixCharacters = boundary ?? 0;
     }
-    _rebuildSystemPrompt(toolNames) {
-        const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
-        const toolSnippets = {};
-        const promptGuidelines = [];
-        for (const name of validToolNames) {
-            const snippet = this._toolPromptSnippets.get(name);
-            if (snippet) {
-                toolSnippets[name] = snippet;
-            }
-            const toolGuidelines = this._toolPromptGuidelines.get(name);
-            if (toolGuidelines) {
-                promptGuidelines.push(...toolGuidelines);
-            }
-        }
-        const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
-        const loaderAppendSystemPrompt = this._resourceLoader.getAppendSystemPrompt();
-        const grokAppend = grokPlaybookAppendForProvider(this.model?.provider);
-        const appendParts = [...loaderAppendSystemPrompt];
-        if (grokAppend) {
-            appendParts.push(grokAppend);
-        }
-        const appendSystemPrompt = appendParts.length > 0 ? appendParts.join("\n\n") : undefined;
-        const loadedSkills = this._resourceLoader.getSkills().skills;
-        const loadedContextFiles = this._resourceLoader.getAgentsFiles().agentsFiles;
-        this._baseSystemPromptOptions = {
+    _getDefaultActiveSkills() {
+        const trustedSkillNames = new Set(this._resourceLoader
+            .getSkills()
+            .skills.filter((skill) => skill.sourceInfo.scope === "user")
+            .map((skill) => skill.name));
+        return this.settingsManager.getDefaultActiveSkills().filter((name) => trustedSkillNames.has(name));
+    }
+    _rebuildSystemPrompt(toolNames, model = this.model) {
+        const defaultActiveSkills = this._getDefaultActiveSkills();
+        const assembled = assembleSessionSystemPrompt({
             cwd: this._cwd,
-            skills: loadedSkills,
-            contextFiles: loadedContextFiles,
-            customPrompt: loaderSystemPrompt,
-            appendSystemPrompt,
-            selectedTools: validToolNames,
-            toolSnippets,
-            promptGuidelines,
-            contextBudget: this._getContextBudgetOptions(),
-        };
-        const built = buildSystemPromptPlan(this._baseSystemPromptOptions);
-        this._baseSystemPromptCacheBoundary = built.cacheBoundary;
-        return built.prompt;
+            toolNames,
+            hasTool: (name) => this._toolRegistry.has(name),
+            toolPromptSnippets: this._toolPromptSnippets,
+            toolPromptGuidelines: this._toolPromptGuidelines,
+            customPrompt: this._resourceLoader.getSystemPrompt(),
+            appendSystemPrompt: this._resourceLoader.getAppendSystemPrompt(),
+            providerAppend: grokPlaybookAppendForProvider(model?.provider),
+            skills: this._resourceLoader.getSkills().skills,
+            activeSkillNames: defaultActiveSkills,
+            activeSkillSource: defaultActiveSkills.length > 0 ? "settings" : undefined,
+            contextFiles: selectContextFilesForModel(this._resourceLoader.getAgentsFiles().agentsFiles, model),
+            contextBudget: this._getContextBudgetOptions(undefined, model),
+        });
+        this._baseSystemPromptOptions = assembled.options;
+        this._baseSystemPromptCacheBoundary = assembled.cacheBoundary;
+        return assembled.prompt;
     }
     // =========================================================================
     // Prompting
     // =========================================================================
     async _runAgentPrompt(messages) {
+        // One identity per top-level run (§16.2): internal retries and
+        // continuations inside this call share it, as does the resource lease.
+        const promptRunId = `prompt-run-${randomUUID()}`;
+        const startedAtEpochMs = Date.now();
+        // Roadmap M2: the lease spans the whole run including internal retries
+        // and continuations, so they share one admission decision (§8.3).
+        const resourceLease = await this._beginResourceGovernedRun(promptRunId);
+        const resourceObservations = this._resourceObservationJournals.get(promptRunId) ?? null;
+        let outcome = "completed";
         try {
             await this.agent.prompt(messages);
             while (await this._handlePostAgentRun()) {
@@ -1707,11 +1694,251 @@ export class AgentSession {
             }
         }
         catch (error) {
+            outcome =
+                this._userAbortRequested || (error instanceof Error && /abort/i.test(error.message)) ? "aborted" : "failed";
             this._publishRuntimeFailure(error);
             throw error;
         }
         finally {
+            if (resourceLease !== null) {
+                // Generation-safe: a stale release after another run acquired the
+                // lease is a no-op instead of clobbering the newer cap (§8.1).
+                this._resourceLeaseController?.release(resourceLease);
+                resourceObservations?.record("resource_lease_released_v1", { promptRunId });
+            }
             this._flushPendingBashMessages();
+            // §16.4 (M4): settle only after every in-run continuation drained.
+            this._emitPromptSettledIfReady({ promptRunId, startedAtEpochMs, outcome, resourceObservations });
+        }
+    }
+    /**
+     * Emit `prompt_settled` when the §16.4 conditions hold. Called exactly
+     * once per promptRunId (from `_runAgentPrompt`'s finally), so the same
+     * run can never emit twice; late-queued messages block emission
+     * conservatively — the continuation run settles under its own id.
+     * Settlement is a UX signal only and must never affect the run (§16.1).
+     */
+    _emitPromptSettledIfReady(input) {
+        try {
+            let state = createPromptSettlementState(input.promptRunId, input.startedAtEpochMs);
+            state = reducePromptSettlement(state, { kind: "terminal", outcome: input.outcome });
+            if (this.isStreaming) {
+                state = reducePromptSettlement(state, { kind: "tool", delta: 1 });
+            }
+            if (this.agent.hasQueuedMessages()) {
+                state = reducePromptSettlement(state, { kind: "continuation", delta: 1 });
+            }
+            const settled = settlePromptIfReady(state, Date.now());
+            if (settled.event !== null) {
+                input.resourceObservations?.record("prompt_settled_v1", settledObservationFacts(settled.event));
+                this._emit(settled.event);
+            }
+        }
+        catch {
+            // Never let settlement bookkeeping break a run.
+        }
+    }
+    /**
+     * Resource governor preflight for one top-level run (roadmap §8, §25.3 M2).
+     *
+     * - `off`: nothing; v0.96.1 observable behavior is preserved.
+     * - `observe` (default): fire-and-forget probe records a decision for the
+     *   §19.4 read-only API; the cap never changes and the prompt is never
+     *   delayed. The pending probe is bounded (~cpuSampleMs) and never rejects.
+     * - `adaptive`/`strict`: bounded blocking probe (default 300 ms deadline),
+     *   then a generation-safe lease applies the effective tool cap for this
+     *   run. The caller's `finally` releases it exactly once.
+     *
+     * Never throws: any probe or policy failure leaves this run ungoverned
+     * (§2.1: probe failure must not crash or block the prompt).
+     */
+    async _beginResourceGovernedRun(promptRunId) {
+        try {
+            const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+            if (resolved.mode === "off") {
+                return null;
+            }
+            const resourceObservations = this._openResourceObservations(promptRunId);
+            const probeOptions = {
+                cwd: this._cwd,
+                maxProbeMs: resolved.maxProbeMs,
+                cpuSampleMs: resolved.cpuSampleMs,
+            };
+            // §7.3: Agent.maxToolConcurrency uses undefined for "unlimited"; the
+            // admission contract uses 0 for the same meaning.
+            const configuredCaps = { maxToolConcurrency: this.agent.maxToolConcurrency ?? 0 };
+            if (resolved.mode === "observe") {
+                void captureHostResourceSnapshot(probeOptions)
+                    .then((snapshot) => {
+                    const decision = decideResourceAdmission({
+                        snapshot,
+                        config: resolved.admission,
+                        configuredCaps,
+                    });
+                    if (this._latestResourcePromptRunId === promptRunId) {
+                        this._lastResourceAdmission = decision;
+                    }
+                    resourceObservations?.record("resource_snapshot_v1", snapshotObservationFacts(snapshot));
+                    resourceObservations?.record("resource_admission_v1", admissionObservationFacts(decision));
+                })
+                    .catch(() => { });
+                return null;
+            }
+            const snapshot = await captureHostResourceSnapshot(probeOptions);
+            const decision = decideResourceAdmission({ snapshot, config: resolved.admission, configuredCaps });
+            if (this._latestResourcePromptRunId === promptRunId) {
+                this._lastResourceAdmission = decision;
+            }
+            resourceObservations?.record("resource_snapshot_v1", snapshotObservationFacts(snapshot));
+            resourceObservations?.record("resource_admission_v1", admissionObservationFacts(decision));
+            this._resourceLeaseController ??= new RunResourceLeaseController({
+                getCap: () => this.agent.maxToolConcurrency,
+                setCap: (cap) => {
+                    this.agent.maxToolConcurrency = cap;
+                },
+            });
+            const lease = this._resourceLeaseController.acquire({ promptRunId, decision });
+            resourceObservations?.record("resource_lease_acquired_v1", {
+                decisionId: decision.decisionId,
+                appliedToolCap: decision.maxToolConcurrency,
+            });
+            return lease;
+        }
+        catch {
+            return null;
+        }
+    }
+    _openResourceObservations(promptRunId) {
+        this._latestResourcePromptRunId = promptRunId;
+        try {
+            const journal = ResourceObservationJournal.open(this._cwd, promptRunId);
+            this._resourceObservations = journal;
+            this._resourceObservationJournals.set(promptRunId, journal);
+            while (this._resourceObservationJournals.size > MAX_RESOURCE_OBSERVATION_JOURNALS) {
+                const oldestPromptRunId = this._resourceObservationJournals.keys().next().value;
+                if (oldestPromptRunId === undefined)
+                    break;
+                this._resourceObservationJournals.delete(oldestPromptRunId);
+            }
+            return journal;
+        }
+        catch {
+            this._resourceObservations = null;
+            this._resourceObservationJournals.delete(promptRunId);
+            return null;
+        }
+    }
+    /** §20.2: record the TUI-side completion sound result in its originating run journal. */
+    recordCompletionSoundResult(promptRunId, result) {
+        const journal = this._resourceObservationJournals.get(promptRunId);
+        journal?.record("completion_sound_result_v1", soundObservationFacts(result));
+        this._resourceObservationJournals.delete(promptRunId);
+        if (this._latestResourcePromptRunId === promptRunId) {
+            this._latestResourcePromptRunId = null;
+            if (this._resourceObservations === journal)
+                this._resourceObservations = null;
+        }
+    }
+    /** §19.4 read-only SDK surface: the most recent resource admission decision, if any. */
+    getCurrentResourceAdmission() {
+        return this._lastResourceAdmission;
+    }
+    /** §19.4 read-only SDK surface: capture a fresh host resource snapshot. */
+    async getHostResourceSnapshot() {
+        const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+        return captureHostResourceSnapshot({
+            cwd: this._cwd,
+            maxProbeMs: resolved.maxProbeMs,
+            cpuSampleMs: resolved.cpuSampleMs,
+        });
+    }
+    /** §19.4 read-only SDK surface: shared workload permit pool state, if any. */
+    getWorkloadPermitSnapshot() {
+        return this._workloadPermitPool?.snapshot() ?? null;
+    }
+    /**
+     * §14.1 shared-budget seam: child subagents must reuse this instance
+     * instead of creating a private pool (host oversubscription). The live
+     * child launcher wiring lands in M6.
+     */
+    get workloadPermitPool() {
+        this._workloadPermitPool ??= new WorkloadPermitPool();
+        return this._workloadPermitPool;
+    }
+    /**
+     * Resource safety gate for the bash boundary (roadmap §9.4/§11, M3).
+     * Runs only in adaptive/strict mode with a recorded admission decision;
+     * observe/off keep v0.96.1 behavior. Never throws: gate machinery
+     * failures leave the command ungated (§2.1), while computed block
+     * verdicts and permit rejections return a bounded §11.3 payload.
+     */
+    async _acquireBashResourcePermit(command, signal) {
+        try {
+            const resolved = resolveResourceGovernorSettings(this.settingsManager.getResourceGovernorSettings());
+            if (resolved.mode !== "adaptive" && resolved.mode !== "strict") {
+                return {};
+            }
+            const decision = this._lastResourceAdmission;
+            if (decision === null) {
+                return {};
+            }
+            const classification = classifyWorkloadCommand(command);
+            this._resourceObservations?.record("workload_classification_v1", classificationObservationFacts(classification));
+            const verdict = decideResourceSafetyGate({ commandSafety: "allowed", classification, decision });
+            if (verdict.kind === "allow") {
+                return {};
+            }
+            if (verdict.kind === "block") {
+                return { blocked: JSON.stringify(verdict.block) };
+            }
+            this._workloadPermitPool ??= new WorkloadPermitPool({ capacity: decision.maxHeavyProcesses });
+            const pool = this._workloadPermitPool;
+            pool.setCapacity(decision.maxHeavyProcesses);
+            const waitStartedMs = Date.now();
+            this._resourceObservations?.record("workload_permit_wait_v1", {
+                workloadClass: classification.workloadClass,
+                weight: verdict.weight,
+            });
+            try {
+                const permit = await pool.acquire({
+                    requestId: `bash-${randomUUID()}`,
+                    promptRunId: this._resourceLeaseController?.activeLease?.promptRunId ?? "unleased",
+                    workloadClass: classification.workloadClass,
+                    weight: verdict.weight,
+                    signal,
+                    // Bounded §10.3 timeout-aware wait; a settings knob can follow later.
+                    timeoutMs: 60_000,
+                });
+                this._resourceObservations?.record("workload_permit_acquired_v1", {
+                    workloadClass: classification.workloadClass,
+                    weight: verdict.weight,
+                    waitMs: Date.now() - waitStartedMs,
+                });
+                return {
+                    release: () => {
+                        permit.release();
+                        this._resourceObservations?.record("workload_permit_released_v1", {
+                            workloadClass: classification.workloadClass,
+                            weight: verdict.weight,
+                        });
+                    },
+                };
+            }
+            catch (error) {
+                const code = error instanceof WorkloadPermitError ? error.code : "queue_overflow";
+                return {
+                    blocked: JSON.stringify({
+                        kind: "resource_pressure",
+                        pressure: decision.pressure,
+                        action: "defer-heavy",
+                        reasonCodes: [...decision.reasons, `resource.permit.${code}`],
+                        requiredAction: RESOURCE_PRESSURE_REQUIRED_ACTION,
+                    }),
+                };
+            }
+        }
+        catch {
+            return {};
         }
     }
     async _handlePostAgentRun() {
@@ -1753,8 +1980,13 @@ export class AgentSession {
         const expandPromptTemplates = options?.expandPromptTemplates ?? true;
         const preflightResult = options?.preflightResult;
         let currentText = redactSensitiveText(text);
-        let promptActiveSkillNames = [...(options?.activeSkillNames ?? [])];
-        let promptActiveSkillSource = options?.activeSkillSource;
+        const defaultActiveSkills = this._getDefaultActiveSkills();
+        let promptActiveSkillNames = mergePromptActiveSkillNames(defaultActiveSkills, options?.activeSkillNames ?? []);
+        let promptActiveSkillSource = defaultActiveSkills.length > 0
+            ? options?.activeSkillSource
+                ? `settings+${options.activeSkillSource}`
+                : "settings"
+            : options?.activeSkillSource;
         let isBangSkillInvocation = false;
         if (expandPromptTemplates) {
             const bangInvocation = parseBangInvocation(text, {
@@ -1766,7 +1998,8 @@ export class AgentSession {
                     ? `/skill:${bangInvocation.skillName} ${bangInvocation.prompt}`
                     : `/skill:${bangInvocation.skillName}`;
                 promptActiveSkillNames = mergePromptActiveSkillNames(promptActiveSkillNames, bangInvocation.activeSkillNames);
-                promptActiveSkillSource = bangInvocation.source;
+                promptActiveSkillSource =
+                    defaultActiveSkills.length > 0 ? `settings+${bangInvocation.source}` : bangInvocation.source;
             }
         }
         let messages;
@@ -1870,8 +2103,8 @@ export class AgentSession {
             const turnSystemPromptOptions = {
                 ...this._baseSystemPromptOptions,
                 contextBudget: this._getContextBudgetOptions(expandedText),
-                ...(promptActiveSkillNames.length > 0 ? { activeSkillNames: promptActiveSkillNames } : {}),
-                ...(promptActiveSkillSource ? { activeSkillSource: promptActiveSkillSource } : {}),
+                activeSkillNames: promptActiveSkillNames,
+                activeSkillSource: promptActiveSkillSource,
             };
             const turnSystemPrompt = buildSystemPromptPlan(turnSystemPromptOptions);
             // Emit before_agent_start extension event
@@ -2234,16 +2467,25 @@ export class AgentSession {
         if (!this._modelRegistry.hasConfiguredAuth(model)) {
             throw new Error(`No API key for ${model.provider}/${model.id}`);
         }
-        // Root-level: block sticky safety models (Fable) unless explicitly allowed in settings.
+        // Root-level: block sticky safety models (Fable) unless the user pinned `--model`.
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        if (resilience.blockStickySafetyModels && isStickySafetyModel(model.id, model.provider)) {
+        if (shouldEjectStickySafetyModel({
+            blockStickySafetyModels: resilience.blockStickySafetyModels,
+            modelPinned: this._modelPinned,
+        }) &&
+            isStickySafetyModel(model.id, model.provider)) {
             throw new Error(stickySafetyBlockMessage(model.id, model.provider));
         }
         // Grok OAuth: block selecting Imagine models as the session chat model.
         assertTextChatModelForCompletion(model.id, model.provider);
         const previousModel = this.model;
         const thinkingLevel = this._getThinkingLevelForModelSwitch();
+        const nextSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames(), model);
         this.agent.state.model = model;
+        this._baseSystemPrompt = nextSystemPrompt;
+        this.agent.state.systemPrompt = this._baseSystemPrompt;
+        this.agent.state.systemPromptCacheBoundary = this._baseSystemPromptCacheBoundary;
+        this.agent.state.systemPromptCacheBoundaryBypass = false;
         this.sessionManager.appendModelChange(model.provider, model.id);
         this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);
         // Re-clamp thinking level for new model's capabilities
@@ -2957,34 +3199,29 @@ export class AgentSession {
      */
     async _checkCompaction(assistantMessage, skipAbortedCheck = true) {
         const settings = this.settingsManager.getCompactionSettings();
-        if (!settings.enabled)
-            return false;
-        // Skip if message was aborted (user cancelled) - unless skipAbortedCheck is false
-        if (skipAbortedCheck && assistantMessage.stopReason === "aborted")
-            return false;
-        const contextWindow = this.model?.contextWindow ?? 0;
-        // Skip overflow check if the message came from a different model.
-        // This handles the case where user switched from a smaller-context model (e.g. opus)
-        // to a larger-context model (e.g. codex) - the overflow error from the old model
-        // shouldn't trigger compaction for the new model.
-        const sameModel = this.model && assistantMessage.provider === this.model.provider && assistantMessage.model === this.model.id;
-        // Image-bearing turns are auto-routed to a vision-capable model (gpt-5.6-luna)
-        // while the session model stays text-only (deepseek). An overflow from that
-        // routed model must still count as the session's own overflow: compaction is
-        // the fix, and the raw context_length_exceeded error must never reach the user.
-        const visionRouteOverflow = this.model != null &&
-            !(this.model.input ?? []).includes("image") &&
-            isVisionRouteModel({ provider: assistantMessage.provider, id: assistantMessage.model });
-        // Skip compaction checks if this assistant message is older than the latest
-        // compaction boundary. This prevents a stale pre-compaction usage/error
-        // from retriggering compaction on the first prompt after compaction.
+        // Stale pre-compaction usage/errors must not retrigger compaction on the
+        // first prompt after one finished.
         const compactionEntry = getLatestCompactionEntry(this.sessionManager.getBranch());
-        const assistantIsFromBeforeCompaction = compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime();
-        if (assistantIsFromBeforeCompaction) {
+        if (shouldSkipCompactionCheck({
+            enabled: settings.enabled,
+            skipAbortedCheck,
+            stopReason: assistantMessage.stopReason,
+            messageTimestamp: assistantMessage.timestamp,
+            latestCompactionTimestamp: compactionEntry ? new Date(compactionEntry.timestamp).getTime() : undefined,
+        })) {
             return false;
         }
-        // Case 1: Overflow - LLM returned context overflow error
-        if ((sameModel || visionRouteOverflow) && isContextOverflow(assistantMessage, contextWindow)) {
+        const contextWindow = this.model?.contextWindow ?? 0;
+        // Case 1: Overflow - LLM returned context overflow error. Only counts when
+        // the failing message belongs to the session model — or to the auto-routed
+        // vision model while the session model is text-only.
+        if (isSessionModelOverflow({
+            message: assistantMessage,
+            contextWindow,
+            sessionProvider: this.model?.provider,
+            sessionModelId: this.model?.id,
+            sessionInputs: this.model?.input,
+        })) {
             if (this._overflowRecoveryAttempts >= MAX_OVERFLOW_RECOVERY_ATTEMPTS) {
                 this._emit({
                     type: "compaction_end",
@@ -3692,20 +3929,7 @@ export class AgentSession {
      * Context overflow errors are NOT retryable (handled by compaction instead).
      */
     _isRetryableError(message) {
-        if (message.stopReason !== "error" || !message.errorMessage)
-            return false;
-        // Context overflow is handled by compaction, not retry
-        const contextWindow = this.model?.contextWindow ?? 0;
-        if (isContextOverflow(message, contextWindow))
-            return false;
-        const err = message.errorMessage;
-        // Billing/quota exhaustion: useless to retry the same model until the
-        // cycle resets, but the turn may still be saved by failing over to the
-        // next candidate, so let _prepareRetry run its failover path.
-        if (isQuotaExhaustionMessage(err))
-            return true;
-        // Shared contract with provider-resilience.ts (Fable safety stop, K3 orphan tool_call_id, terminated).
-        return isTransientProviderErrorMessage(err);
+        return isRetryableAssistantError(message, this.model?.contextWindow ?? 0);
     }
     /**
      * Retry policy + callbacks shared by compaction and branch-summary summarization calls.
@@ -3742,8 +3966,12 @@ export class AgentSession {
     /** Eject sticky safety model at prompt boundary (session resume / leftover default). */
     async _ejectStickySafetyModelIfNeeded() {
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        if (!resilience.blockStickySafetyModels)
+        if (!shouldEjectStickySafetyModel({
+            blockStickySafetyModels: resilience.blockStickySafetyModels,
+            modelPinned: this._modelPinned,
+        })) {
             return;
+        }
         const current = this.model;
         if (!current || !isStickySafetyModel(current.id, current.provider))
             return;
@@ -3771,11 +3999,17 @@ export class AgentSession {
      */
     async _maybeFailoverFromSafetyStop(message) {
         const resilience = resolveProviderResilience(this.settingsManager.getProviderResilienceSettings());
-        if (!resilience.autoFailoverOnSafetyStop)
+        if (!shouldHonorSafetyFailover({
+            autoFailoverOnSafetyStop: resilience.autoFailoverOnSafetyStop,
+            modelPinned: this._modelPinned,
+            modelId: this.model?.id,
+            provider: this.model?.provider,
+        })) {
             return undefined;
+        }
         // Fire on safety-stop FPs AND on billing/quota exhaustion: both mean the
         // current model cannot finish this turn and same-model retry is useless.
-        if (!isContentSafetyStopMessage(message.errorMessage) && !isQuotaExhaustionMessage(message.errorMessage)) {
+        if (!isFailoverTriggerError(message.errorMessage)) {
             return undefined;
         }
         const current = this.model;
@@ -3783,10 +4017,10 @@ export class AgentSession {
         // claude-opus-5 emits the same stop_reason=refusal FP; same-model retry is useless.
         // v10.3-Ω: mark the model that just refused so we never re-pick it this turn.
         if (current)
-            this._refusedModels.add(`${current.provider}/${current.id}`);
+            this._refusedModels.add(failoverModelKey(current.provider, current.id));
         const pick = pickFailoverCandidate(resilience.failoverCandidates, current ? { provider: current.provider, id: current.id } : undefined, (c) => {
             // Skip any model that already refused/failed this turn → advance the chain.
-            if (this._refusedModels.has(`${c.provider}/${c.id}`))
+            if (this._refusedModels.has(failoverModelKey(c.provider, c.id)))
                 return false;
             const next = this._modelRegistry.find(c.provider, c.id);
             if (!next)
@@ -3804,34 +4038,32 @@ export class AgentSession {
         }
         catch {
             // setModel failed (auth/guard) — blacklist so next retry advances further.
-            this._refusedModels.add(`${pick.provider}/${pick.id}`);
+            this._refusedModels.add(failoverModelKey(pick.provider, pick.id));
             return undefined;
         }
     }
     async _prepareRetry(message) {
         const settings = this.settingsManager.getRetrySettings();
-        if (!settings.enabled) {
-            return false;
-        }
-        this._retryAttempt++;
-        if (this._retryAttempt > settings.maxRetries) {
-            // Preserve the completed attempt count so post-run handling can emit the final failure.
-            this._retryAttempt--;
+        const maxRetries = retryBudgetForAssistantError(message, settings.maxRetries);
+        const attempt = nextRetryAttempt({
+            enabled: settings.enabled,
+            completedAttempts: this._retryAttempt,
+            maxRetries,
+        });
+        if (attempt === undefined)
             return false;
-        }
+        this._retryAttempt = attempt;
         // Content/safety stop (Fable/Opus/Sonnet): switch model BEFORE delay so retry is not same-model refusal.
         const failoverTo = await this._maybeFailoverFromSafetyStop(message);
         // Safety stops are usually immediate false positives — short delay after failover, full backoff otherwise.
-        const delayMs = failoverTo
-            ? Math.min(400, settings.baseDelayMs)
-            : settings.baseDelayMs * 2 ** (this._retryAttempt - 1);
+        const delayMs = computeRetryDelayMs(settings.baseDelayMs, attempt, failoverTo !== undefined);
         const errorMessage = failoverTo
             ? `${message.errorMessage || "content/safety stop"} → failover ${failoverTo}`
             : message.errorMessage || "Unknown error";
         this._emit({
             type: "auto_retry_start",
-            attempt: this._retryAttempt,
-            maxAttempts: settings.maxRetries,
+            attempt,
+            maxAttempts: maxRetries,
             delayMs,
             errorMessage,
         });
@@ -4343,21 +4575,6 @@ export class AgentSession {
         return this._extensionRunner;
     }
 }
-// ---------------------------------------------------------------------------
-// Context budget constants
-// ---------------------------------------------------------------------------
-/** Fraction of contextWindow reserved for model response generation. */
-const RESPONSE_RESERVE_RATIO = 0.2;
-/** Fraction of contextWindow held back as safety margin for token-count imprecision. */
-const SAFETY_MARGIN_RATIO = 0.1;
-// Default prompt budget = contextWindow - responseReserve - safetyMargin.
-// With the defaults above (0.2 + 0.1) this yields ~0.70 of contextWindow, but it
-// stays correct when responseReserve is overridden by model.maxTokens.
-/** Absolute floor for maxPromptTokens — below this the budget is meaningless. */
-const MIN_PROMPT_TOKENS = 4000;
-/** Legacy defaults when no model contextWindow is known. */
-const LEGACY_MAX_PROMPT_TOKENS = 60_000;
-const LEGACY_RESPONSE_RESERVE_TOKENS = 8_192;
 function parsePositiveIntegerEnv(name) {
     const raw = process.env[name];
     if (raw === undefined || raw.trim() === "") {