mixdog 0.9.0 → 0.9.2

package/src/runtime/agent/orchestrator/session/manager.mjs

@@ -12,17 +12,16 @@ import { fetchOAuthUsageSnapshot } from '../providers/oauth-usage.mjs';
 import {
     recallFastTrackCompactMessages,
     semanticCompactMessages,
+    pruneToolOutputsUnanchored,
+    effectiveBudget as compactEffectiveBudget,
     compactTypeIsRecallFastTrack,
     compactTypeIsSemantic,
     normalizeCompactType,
     DEFAULT_COMPACT_TYPE,
     SUMMARY_PREFIX,
-    DEFAULT_COMPACTION_BUFFER_RATIO,
-    compactionBufferTokensForBoundary,
-    normalizeCompactionBufferRatio,
     drainSessionCycle1,
 } from './compact.mjs';
-import { estimateMessagesTokens, estimateRequestReserveTokens, estimateTranscriptContextUsage } from './context-utils.mjs';
+import { estimateMessagesTokens, estimateRequestReserveTokens, estimateTranscriptContextUsage, resolveCompactTriggerTokens } from './context-utils.mjs';
 import { getMcpTools } from '../mcp/client.mjs';
 import { getInternalTools, executeInternalTool } from '../internal-tools.mjs';
 import { BUILTIN_TOOLS } from '../tools/builtin/builtin-tools.mjs';
@@ -41,7 +40,7 @@ import { updateJsonAtomicSync } from '../../../shared/atomic-file.mjs';
 import { appendAgentTrace } from '../agent-trace.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
 import { maxMtimeRecursive } from '../cache-mtime.mjs';
-import { getHiddenRole, getRoleInstructionDir, listHiddenRoleNames } from '../internal-roles.mjs';
+import { getHiddenAgent, getAgentInstructionDir, listHiddenAgentNames } from '../internal-agents.mjs';
 import { DEFAULT_ACTIVITY_HEARTBEAT_MS } from '../stall-policy.mjs';
 import {
     buildGatewayLimits,
@@ -185,34 +184,34 @@ function _buildLeadMetaContext() {
     }
 }
 
-// BP4-adjacent role-specific data cache — keyed by role. webhook / schedule
-// roles each have their own scoped instruction set; other roles return ''.
-const _roleSpecificCache = new Map(); // role → { value, mtime }
-function _buildRoleSpecific(currentRole) {
+// BP4-adjacent agent-specific data cache — keyed by agent. webhook / schedule
+// agents each have their own scoped instruction set; other agents return ''.
+const _roleSpecificCache = new Map(); // agent → { value, mtime }
+function _buildAgentSpecific(currentAgent) {
     if (!_rulesBuilder || typeof _rulesBuilder.buildAgentRoleSpecificContent !== 'function') return '';
-    if (!currentRole) return '';
+    if (!currentAgent) return '';
     const PLUGIN_ROOT = mixdogRoot();
     const DATA_DIR = resolvePluginData();
     const RULES_DIR = join(PLUGIN_ROOT, 'rules');
-    const roleInstructionDir = getRoleInstructionDir(currentRole);
+    const roleInstructionDir = getAgentInstructionDir(currentAgent);
     const mtime = maxMtimeRecursive([
         join(RULES_DIR, 'shared'),
         join(DATA_DIR, 'mixdog-config.json'),
         join(DATA_DIR, 'webhooks'),
         join(DATA_DIR, 'schedules'),
         ...(roleInstructionDir ? [join(DATA_DIR, roleInstructionDir)] : []),
-        join(PLUGIN_ROOT, 'defaults', 'hidden-roles.json'),
+        join(PLUGIN_ROOT, 'defaults', 'agents.json'),
     ]);
-    const entry = _roleSpecificCache.get(currentRole);
+    const entry = _roleSpecificCache.get(currentAgent);
     if (entry && mtime <= entry.mtime) {
         return entry.value;
     }
     try {
-        const built = _rulesBuilder.buildAgentRoleSpecificContent({ PLUGIN_ROOT, DATA_DIR, currentRole });
-        _roleSpecificCache.set(currentRole, { mtime, value: built });
+        const built = _rulesBuilder.buildAgentRoleSpecificContent({ PLUGIN_ROOT, DATA_DIR, currentAgent });
+        _roleSpecificCache.set(currentAgent, { mtime, value: built });
         return built;
     } catch (e) {
-        throw new Error(`[session] role-specific rules build failed (role: ${currentRole}): ${e.message}`);
+        throw new Error(`[session] agent-specific rules build failed (agent: ${currentAgent}): ${e.message}`);
     }
 }
 
@@ -349,6 +348,7 @@ const AGENT_STRING_PERMISSION_READ_ALLOW = Object.freeze([
     'explore',
     'search',
     'web_fetch',
+    'Skill',
 ]);
 
 function stringToolPermissionAllowList(toolPermission) {
@@ -369,6 +369,7 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'explore',
     'search',
     'web_fetch',
+    'Skill',
 ]);
 
 function applyToolPermissionNarrowing(tools, toolPermission, warnRole = null) {
@@ -401,12 +402,14 @@ function applyToolPermissionNarrowing(tools, toolPermission, warnRole = null) {
     return tools;
 }
 
-function recursiveWrapperToolNameForPublicAgentRole(role) {
-    if (!role) return null;
-    const key = String(role).trim();
-    for (const hiddenName of listHiddenRoleNames()) {
-        const def = getHiddenRole(hiddenName);
+function recursiveWrapperToolNameForPublicAgent(agent) {
+    if (!agent) return null;
+    const key = String(agent).trim();
+    if (key === 'explore') return 'explore';
+    for (const hiddenName of listHiddenAgentNames()) {
+        const def = getHiddenAgent(hiddenName);
         const invokedBy = typeof def?.invokedBy === 'string' ? def.invokedBy.trim() : '';
+        if (hiddenName === key && invokedBy) return invokedBy;
         if (invokedBy && invokedBy === key) return invokedBy;
     }
     return null;
@@ -416,7 +419,7 @@ function finalizeSessionToolList(tools, {
     schemaAllowedTools = null,
     disallowedTools = null,
     ownerIsAgent = false,
-    resolvedRole = null,
+    resolvedAgent = null,
 } = {}) {
     let out = Array.isArray(tools) ? tools : [];
     const hasCallerAllow = Array.isArray(schemaAllowedTools);
@@ -429,7 +432,7 @@ function finalizeSessionToolList(tools, {
         const denySet = new Set(callerDeny.map(n => n.toLowerCase()));
         out = out.filter(t => !denySet.has(String(t?.name || '').toLowerCase()));
     }
-    const recursiveDeny = ownerIsAgent ? recursiveWrapperToolNameForPublicAgentRole(resolvedRole) : null;
+    const recursiveDeny = ownerIsAgent ? recursiveWrapperToolNameForPublicAgent(resolvedAgent) : null;
     if (recursiveDeny) {
         const deny = recursiveDeny.toLowerCase();
         out = out.filter(t => String(t?.name || '').toLowerCase() !== deny);
@@ -639,38 +642,9 @@ function providerNameOf(provider) {
     if (typeof provider === 'string') return provider.toLowerCase();
     return String(provider?.name || provider?.id || '').toLowerCase();
 }
-// Buffer-percent parsing trap: normalizeCompactionBufferRatio treats any value
-// > 1 as a percent (n/100) and any value <= 1 as a literal ratio. That is wrong
-// for percent-NAMED inputs: bufferPercent / bufferPct / *_BUFFER_PERCENT = 1
-// means 1% (0.01), but the shared normalizer would read it as the literal ratio
-// 1.0 (100%). Resolve percent-named and ratio-named inputs with the correct
-// semantics here, before handing a finished ratio to the shared helper:
-//   percent inputs: n  -> n/100   (1 -> 0.01, 10 -> 0.10)
-//   ratio inputs:   n  -> n>1 ? n/100 : n   (0.01 -> 0.01, 10 -> 0.10 legacy)
-function resolveBufferRatioCandidate(percentInputs, ratioInputs) {
-    for (const raw of percentInputs) {
-        const n = Number(raw);
-        if (Number.isFinite(n) && n > 0) return Math.min(1, n / 100);
-    }
-    for (const raw of ratioInputs) {
-        const n = Number(raw);
-        if (Number.isFinite(n) && n > 0) return n > 1 ? n / 100 : n;
-    }
-    return null;
-}
-function compactBufferRatioForConfig(cfg = {}) {
-    const resolved = resolveBufferRatioCandidate(
-        [cfg.bufferPercent, cfg.bufferPct, process.env.MIXDOG_AGENT_COMPACT_BUFFER_PERCENT],
-        [cfg.bufferRatio, cfg.bufferFraction, process.env.MIXDOG_AGENT_COMPACT_BUFFER_RATIO],
-    );
-    return normalizeCompactionBufferRatio(resolved, DEFAULT_COMPACTION_BUFFER_RATIO);
-}
-function compactBufferRatioForSession(session) {
-    return compactBufferRatioForConfig(session?.compaction || {});
-}
 // Carry the percent/ratio-named buffer config from a compaction config object
-// onto session.compaction so downstream parsers (compactBufferRatioForSession,
-// loop.resolveCompactBufferRatio, contextStatus) honor a configured buffer
+// onto session.compaction so the shared compact-policy parser honors configured
+// buffer
 // percent/ratio. Only finite positive values are copied; absent fields stay
 // undefined so the default-ratio fallback still applies.
 function preserveBufferConfigFields(cfg = {}) {
@@ -681,69 +655,6 @@ function preserveBufferConfigFields(cfg = {}) {
     }
     return out;
 }
-const LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
-function isPersistedZeroBufferTelemetry(cfg = {}, boundaryTokens = 0) {
-    const boundary = positiveContextWindow(boundaryTokens);
-    if (!boundary) return false;
-    if (positiveContextWindow(process.env.MIXDOG_AGENT_COMPACT_BUFFER_TOKENS)) return false;
-    if (Number.isFinite(Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_PERCENT)) && Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_PERCENT) > 0) return false;
-    if (Number.isFinite(Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_RATIO)) && Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_RATIO) > 0) return false;
-    for (const key of ['bufferPercent', 'bufferPct', 'bufferFraction']) {
-        const n = Number(cfg?.[key]);
-        if (Number.isFinite(n) && n > 0) return false;
-    }
-    const ratio = Number(cfg?.bufferRatio);
-    if (Number.isFinite(ratio) && ratio > 0) return false;
-    const explicitTokens = Number(cfg?.bufferTokens ?? cfg?.buffer);
-    if (!Number.isFinite(explicitTokens) || explicitTokens !== 0) return false;
-    return true;
-}
-function isLegacyDefaultBufferTelemetry(cfg = {}, boundaryTokens = 0) {
-    const boundary = positiveContextWindow(boundaryTokens);
-    if (!boundary) return false;
-    if (positiveContextWindow(process.env.MIXDOG_AGENT_COMPACT_BUFFER_TOKENS)) return false;
-    if (Number.isFinite(Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_PERCENT)) && Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_PERCENT) > 0) return false;
-    if (Number.isFinite(Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_RATIO)) && Number(process.env.MIXDOG_AGENT_COMPACT_BUFFER_RATIO) > 0) return false;
-    // Percent/fraction-named fields are treated as operator config. The legacy
-    // default telemetry always persisted bufferTokens + bufferRatio after a
-    // check/compact pass, so only that shape is migrated away.
-    for (const key of ['bufferPercent', 'bufferPct', 'bufferFraction']) {
-        const n = Number(cfg?.[key]);
-        if (Number.isFinite(n) && n > 0) return false;
-    }
-    const explicitTokens = positiveContextWindow(cfg?.bufferTokens ?? cfg?.buffer);
-    const ratio = Number(cfg?.bufferRatio);
-    if (!explicitTokens || !Number.isFinite(ratio) || Math.abs(ratio - LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO) > 1e-9) return false;
-    const expectedTokens = Math.floor(boundary * LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO);
-    const cfgBoundary = positiveContextWindow(cfg?.boundaryTokens);
-    const cfgTrigger = positiveContextWindow(cfg?.triggerTokens);
-    return explicitTokens === expectedTokens
-        || (cfgBoundary === boundary && cfgTrigger > 0 && explicitTokens === Math.max(0, boundary - cfgTrigger));
-}
-function compactBufferConfigForBoundary(cfg = {}, boundaryTokens = 0) {
-    const base = cfg || {};
-    if (!isLegacyDefaultBufferTelemetry(base, boundaryTokens)
-        && !isPersistedZeroBufferTelemetry(base, boundaryTokens)) {
-        return base;
-    }
-    return {
-        ...base,
-        bufferTokens: null,
-        buffer: null,
-        bufferRatio: null,
-    };
-}
-function compactBufferTokensForSession(session, boundaryTokens) {
-    const cfg = compactBufferConfigForBoundary(session?.compaction || {}, boundaryTokens);
-    const explicit = positiveContextWindow(cfg.bufferTokens ?? cfg.buffer)
-        || positiveContextWindow(process.env.MIXDOG_AGENT_COMPACT_BUFFER_TOKENS)
-        || 0;
-    return compactionBufferTokensForBoundary(boundaryTokens, {
-        explicitTokens: explicit,
-        ratio: compactBufferRatioForConfig(cfg),
-        maxRatio: 0.25,
-    });
-}
 const COMPACT_TARGET_RATIO = 0.02;
 const COMPACT_TARGET_MIN_TOKENS = 4_000;
 const COMPACT_TARGET_MAX_TOKENS = 16_000;
@@ -774,15 +685,32 @@ function defaultEffectiveContextWindowPercent(provider) {
     // capacity so /context, the TUI statusline, and gateway telemetry agree.
     return 90;
 }
+const PROVIDER_SYNTHETIC_CONTEXT_DEFAULT = 1_000_000;
+function providerRawContextWindow(info, catalogInfo) {
+    if (!info || typeof info !== 'object') return null;
+    const fromApiFields = positiveContextWindow(info.context_window)
+        || positiveContextWindow(info.max_context_window);
+    if (fromApiFields) return fromApiFields;
+    const fromCache = positiveContextWindow(info.contextWindow)
+        || positiveContextWindow(info.maxContextWindow);
+    if (!fromCache) return null;
+    const catalogWindow = positiveContextWindow(catalogInfo?.contextWindow)
+        || positiveContextWindow(catalogInfo?.maxContextWindow)
+        || positiveContextWindow(catalogInfo?.context_window)
+        || positiveContextWindow(catalogInfo?.max_context_window);
+    if (fromCache === PROVIDER_SYNTHETIC_CONTEXT_DEFAULT
+        && catalogWindow
+        && fromCache !== catalogWindow) {
+        return null;
+    }
+    return fromCache;
+}
 function resolveSessionContextMeta(provider, model, seed = {}) {
     const info = typeof provider?.getCachedModelInfo === 'function'
         ? provider.getCachedModelInfo(model)
         : null;
     const catalogInfo = getModelMetadataSync(model, providerNameOf(provider));
-    const rawContextWindow = positiveContextWindow(info?.contextWindow)
-        || positiveContextWindow(info?.maxContextWindow)
-        || positiveContextWindow(info?.context_window)
-        || positiveContextWindow(info?.max_context_window)
+    const rawContextWindow = providerRawContextWindow(info, catalogInfo)
         || positiveContextWindow(catalogInfo?.contextWindow)
         || positiveContextWindow(catalogInfo?.maxContextWindow)
         || positiveContextWindow(catalogInfo?.context_window)
@@ -841,16 +769,7 @@ function resolveSessionContextMeta(provider, model, seed = {}) {
     };
 }
 function compactTriggerForSession(session, boundaryTokens) {
-    const boundary = positiveContextWindow(boundaryTokens);
-    if (!boundary) return null;
-    const autoLimit = positiveContextWindow(session?.autoCompactTokenLimit ?? session?.compaction?.autoCompactTokenLimit);
-    // Only honor an explicit auto-compact limit that sits STRICTLY BELOW the
-    // boundary. A persisted value == boundary (or >=) is a legacy derived
-    // full-window artifact; honoring it collapses the compaction buffer to 0,
-    // so fall through to the default boundary trigger instead.
-    if (autoLimit && autoLimit < boundary) return Math.max(1, autoLimit);
-    const buffer = compactBufferTokensForSession(session, boundary);
-    return Math.max(1, boundary - buffer);
+    return resolveCompactTriggerTokens(session, boundaryTokens);
 }
 // Test-only exports for the legacy auto-compact-limit migration + buffer-config
 // preservation (see scripts/compact-trigger-migration-smoke.mjs).
@@ -904,10 +823,12 @@ function addCompactUsageToSession(session, usage) {
     const outputTokens = usage.outputTokens || 0;
     const cachedTokens = usage.cachedTokens || 0;
     const cacheWriteTokens = usage.cacheWriteTokens || 0;
+    const uncachedInputTokens = uncachedInputTokensForProvider(session.provider, inputTokens, cachedTokens, cacheWriteTokens);
     session.totalInputTokens = (session.totalInputTokens || 0) + inputTokens;
     session.totalOutputTokens = (session.totalOutputTokens || 0) + outputTokens;
     session.totalCachedReadTokens = (session.totalCachedReadTokens || 0) + cachedTokens;
     session.totalCacheWriteTokens = (session.totalCacheWriteTokens || 0) + cacheWriteTokens;
+    session.totalUncachedInputTokens = (session.totalUncachedInputTokens || 0) + uncachedInputTokens;
     session.tokensCumulative = (session.tokensCumulative || 0) + inputTokens + outputTokens;
 }
 async function runRecallFastTrackForSession(session, messages, opts = {}) {
@@ -977,6 +898,18 @@ async function runRecallFastTrackForSession(session, messages, opts = {}) {
     }
     return { query, querySha, recallText: [`session_id=${sessionId}`, cycle1Text, recallText].map(v => String(v || '').trim()).filter(Boolean).join('\n\n') };
 }
+// Element-identity change detection (mirrors loop.mjs messagesArrayChanged): two
+// arrays are "unchanged" only when same length AND every slot is the same object
+// reference. Used to reject a no-op prune (which returns a fresh array whose
+// elements are the untouched originals) from being accepted as a recovery.
+function messagesChanged(before, after) {
+    if (!Array.isArray(before) || !Array.isArray(after)) return before !== after;
+    if (before.length !== after.length) return true;
+    for (let i = 0; i < before.length; i += 1) {
+        if (before[i] !== after[i]) return true;
+    }
+    return false;
+}
 async function runSessionCompaction(session, opts = {}) {
     if (!session || session.closed === true) return null;
     const mode = opts.mode === 'auto' ? 'auto' : 'manual';
@@ -991,7 +924,16 @@ async function runSessionCompaction(session, opts = {}) {
         if (force) throw new Error('compact: no context window is available for this session');
         return null;
     }
-    const reserveTokens = estimateRequestReserveTokens(session.tools || []);
+    // Reserve must mirror loop.mjs (buildCompactPolicy): request reserve (tool
+    // schema) PLUS the configured reserve (session.compaction.reservedTokens or
+    // MIXDOG_AGENT_COMPACT_RESERVED_TOKENS env). The old request-only value left
+    // the manual / auto-clear compact budget without the configured headroom the
+    // loop path reserves, so a compacted transcript could overflow on next send.
+    const requestReserveTokens = estimateRequestReserveTokens(session.tools || []);
+    const configuredReserveTokens = positiveContextWindow(session.compaction?.reservedTokens)
+        || positiveContextWindow(process.env.MIXDOG_AGENT_COMPACT_RESERVED_TOKENS)
+        || 0;
+    const reserveTokens = requestReserveTokens + configuredReserveTokens;
     const beforeMessageTokens = estimateMessagesTokens(messages);
     const triggerTokens = compactTriggerForSession(session, boundary)
         || positiveContextWindow(session.compaction?.triggerTokens)
@@ -1041,7 +983,11 @@ async function runSessionCompaction(session, opts = {}) {
                 recallText: recallPayload.recallText,
                 query: recallPayload.query,
                 querySha: recallPayload.querySha,
-                allowEmptyRecall: true,
+                // Ingest just ran on the live transcript, so an empty recall dump
+                // means the memory pipeline is broken — do NOT erase history
+                // behind an empty summary shell. Empty recall now throws and is
+                // handled by the semantic fallback below (or recorded failure).
+                allowEmptyRecall: false,
                 tailTurns: positiveContextWindow(session.compaction?.tailTurns) || 2,
                 keepTokens: positiveContextWindow(session.compaction?.keepTokens ?? session.compaction?.keep?.tokens),
                 preserveRecentTokens: positiveContextWindow(session.compaction?.preserveRecentTokens),
@@ -1055,6 +1001,48 @@ async function runSessionCompaction(session, opts = {}) {
             try {
                 process.stderr.write(`[session] recall-fasttrack ${mode} compact failed (sess=${session.id || 'unknown'}): ${err?.message || err}\n`);
             } catch { /* best-effort */ }
+            // Degraded-compact fallback: recall-fasttrack failed (empty recall,
+            // ingest error, fit failure). Before recording a hard failure, try
+            // the semantic path once so auto-clear/manual compaction still makes
+            // progress WITHOUT shipping an empty-recall summary. History is only
+            // replaced when the semantic summary actually succeeds.
+            if (semanticCompactionEnabledForSession(session)
+                && provider && typeof provider.send === 'function') {
+                try {
+                    semanticCompactResult = await semanticCompactMessages(
+                        provider,
+                        messages,
+                        opts.model || session.model,
+                        budget,
+                        {
+                            reserveTokens,
+                            providerName: session.provider || provider?.name || null,
+                            sessionId: opts.sessionId || session.id || null,
+                            signal: opts.signal || null,
+                            promptCacheKey: session.promptCacheKey || null,
+                            providerCacheKey: session.promptCacheKey || null,
+                            timeoutMs: positiveContextWindow(session.compaction?.timeoutMs) || 30_000,
+                            tailTurns: positiveContextWindow(session.compaction?.tailTurns) || 2,
+                            keepTokens: positiveContextWindow(session.compaction?.keepTokens ?? session.compaction?.keep?.tokens),
+                            preserveRecentTokens: positiveContextWindow(session.compaction?.preserveRecentTokens),
+                            force: true,
+                        },
+                    );
+                    if (Array.isArray(semanticCompactResult?.messages)) {
+                        compacted = semanticCompactResult.messages;
+                        compactError = null;
+                        addCompactUsageToSession(session, semanticCompactResult.usage);
+                        try {
+                            process.stderr.write(`[session] degraded compact: recall-fasttrack failed, semantic fallback succeeded (sess=${session.id || 'unknown'}, mode=${mode})\n`);
+                        } catch { /* best-effort */ }
+                    }
+                } catch (fallbackErr) {
+                    semanticCompactError = fallbackErr;
+                    try {
+                        process.stderr.write(`[session] degraded compact: semantic fallback also failed (sess=${session.id || 'unknown'}): ${fallbackErr?.message || fallbackErr}\n`);
+                    } catch { /* best-effort */ }
+                }
+            }
         }
     } else if (compactTypeIsSemantic(compactType)) {
         try {
@@ -1098,6 +1086,32 @@ async function runSessionCompaction(session, opts = {}) {
     if (!compacted && !compactError) {
         compactError = new Error(`${compactType} compact produced no messages`);
     }
+    // Anchor-independent prune safety net (mirror loop.mjs compact catch): when a
+    // non-recall (semantic) compact failed, try one non-LLM prune that needs no
+    // user anchor before recording failure, so Lead manual / auto-clear paths
+    // recover the same transcripts the loop path does. Gated off the recall
+    // path — a recall failure keeps its original contract (no silent prune).
+    if (!compacted && !recallFastTrackError) {
+        try {
+            const acceptThreshold = compactEffectiveBudget(budget, { reserveTokens });
+            const salvaged = pruneToolOutputsUnanchored(messages, budget, { reserveTokens });
+            // pruneToolOutputsUnanchored ALWAYS returns a fresh reconciled array
+            // (never the input identity), so `salvaged !== messages` is always
+            // true and cannot detect a no-op. Compare by element identity so a
+            // transcript that already fit (nothing pruned) is NOT falsely accepted
+            // as a recovery — that would clear compactError and unconditionally
+            // invalidate providerState for an unchanged transcript.
+            if (Array.isArray(salvaged)
+                && messagesChanged(messages, salvaged)
+                && estimateMessagesTokens(salvaged) <= acceptThreshold) {
+                compacted = salvaged;
+                compactError = null;
+                try {
+                    process.stderr.write(`[session] compact fallback prune recovered (sess=${session.id || 'unknown'}, mode=${mode})\n`);
+                } catch { /* best-effort */ }
+            }
+        } catch { /* fall through to failure record */ }
+    }
     if (!compacted) {
         const now = Date.now();
         session.compaction = {
@@ -1506,7 +1520,7 @@ async function _tryBridgeExplicitPrefetch(session, explicitPrefetch) {
 // Preset shape: { name, provider, model, effort?, fast?, tools? }
 //
 // Agent Runtime integration:
-//   opts.taskType / opts.role / opts.profileId — enables profile-aware routing.
+//   opts.taskType / opts.agent / opts.profileId — enables profile-aware routing.
 //     Rule-based SmartRouter resolves these synchronously; the resolved
 //     profile controls context filtering (skip.skills/memory/etc) and cache
 //     strategy. If no rule matches, falls back to classic preset behavior.
@@ -1519,13 +1533,13 @@ export function createSession(opts) {
     // --- Agent Runtime profile resolution (best-effort, sync) ---
     let profile = opts.profile || null;
     let providerCacheOpts = opts.providerCacheOpts || null;
-    if (!profile && (opts.taskType || opts.role || opts.profileId)) {
+    if (!profile && (opts.taskType || opts.agent || opts.profileId)) {
         const agentRuntime = getAgentRuntimeSync();
         if (agentRuntime) {
             try {
                 const resolved = agentRuntime.resolveSync({
                     taskType: opts.taskType,
-                    role: opts.role,
+                    agent: opts.agent,
                     profileId: opts.profileId,
                     preset: presetObj?.name || (typeof opts.preset === 'string' ? opts.preset : null),
                     provider: opts.provider || presetObj?.provider,
@@ -1567,25 +1581,26 @@ export function createSession(opts) {
     const id = `sess_${process.pid}_${nextId++}_${Date.now()}_${randomBytes(16).toString('hex')}`;
     const messages = [];
     const ownerIsAgent = isAgentOwner(opts.owner);
-    const resolvedRole = opts.role || profile?.taskType || null;
-    const hiddenRole = getHiddenRole(resolvedRole);
-    const isRetrievalRole = hiddenRole?.kind === 'retrieval';
-    // Skill schema is fixed; the compact manifest is discovered once through
-    // the mtime-cached frontmatter index so BP1 tells every role which Skill()
-    // names are available without loading full SKILL.md bodies.
-    const skills = opts.skipSkills ? [] : collectSkillsCached(opts.cwd);
+    const resolvedAgent = opts.agent || opts.role || profile?.taskType || null;
+    const hiddenAgent = getHiddenAgent(resolvedAgent);
+    const isRetrievalAgent = hiddenAgent?.kind === 'retrieval';
+    // Skill schema is fixed for public agent sessions, but hidden retrieval /
+    // maintenance roles are deliberately narrowed away from the Skill tool.
+    // Do not leak a Skill manifest into those hidden prompts when no Skill()
+    // loader is available.
+    const skills = (opts.skipSkills || hiddenAgent) ? [] : collectSkillsCached(opts.cwd);
 
     // BP1 is shared tool policy (+ compact skill manifest in compose). BP2 is
     // role/system rules. User-defined schedules/webhooks ride as normal user
     // context below so event data does not rewrite BP3 memory/meta.
-    const agentRulesRole = opts.role || profile?.taskType || null;
-    const agentRulesProfile = isRetrievalRole ? 'retrieval' : 'full';
+    const agentRulesAgent = opts.agent || opts.role || profile?.taskType || null;
+    const agentRulesProfile = isRetrievalAgent ? 'retrieval' : 'full';
     const skipAgentRules = opts.skipAgentRules === true;
     // Retrieval roles already inject a compact # Tool Use via BP2; skip the full BP1 shared tool policy to avoid duplicating it.
-    const injectedRules = (skipAgentRules || isRetrievalRole) ? '' : _buildSharedRules();
+    const injectedRules = (skipAgentRules || isRetrievalAgent) ? '' : _buildSharedRules();
     const roleRules = skipAgentRules ? '' : (ownerIsAgent ? _buildAgentRules(agentRulesProfile) : _buildLeadRules());
     const metaContext = skipAgentRules ? '' : (ownerIsAgent ? '' : _buildLeadMetaContext());
-    const roleSpecific = ownerIsAgent && !skipAgentRules ? _buildRoleSpecific(agentRulesRole) : '';
+    const roleSpecific = ownerIsAgent && !skipAgentRules ? _buildAgentSpecific(agentRulesAgent) : '';
     // Agent sessions must not inherit role/profile/preset tool narrowing: Pool
     // B and Pool C share one bit-identical tool schema to maximize provider
     // prefix reuse, and permission differences are enforced only at call time. Raw
@@ -1612,7 +1627,7 @@ export function createSession(opts) {
     // fail closed (zero tools) rather than silently falling back to the full
     // preset, which would grant the role more surface than declared.
     if (ownerIsAgent) {
-        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, opts.role || null);
+        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, opts.agent || null);
     }
 
     const { baseRules, stableSystemContext, sessionMarker, volatileTail } = composeSystemPrompt({
@@ -1622,7 +1637,7 @@ export function createSession(opts) {
         metaContext: metaContext || undefined,
         skipRoleCatalog: !ownerIsAgent,
         profile: profile || undefined,
-        role: resolvedRole,
+        agent: resolvedAgent,
         workflowContext: opts.workflowContext || null,
         workspaceContext: opts.workspaceContext || null,
         coreMemoryContext: opts.coreMemoryContext || null,
@@ -1678,17 +1693,17 @@ export function createSession(opts) {
     const hasCallerAllow = Array.isArray(opts.schemaAllowedTools);
     const tools = finalizeSessionToolList(toolsForRouting, {
         schemaAllowedTools: hasCallerAllow ? opts.schemaAllowedTools : null,
-        disallowedTools: opts.disallowedTools,
+        disallowedTools: hiddenAgent ? [...(Array.isArray(opts.disallowedTools) ? opts.disallowedTools : []), 'Skill'] : opts.disallowedTools,
         ownerIsAgent,
-        resolvedRole,
+        resolvedAgent,
     });
 
     // Unified-shard policy — no broad role-specific schema filter. Keep
     // agent schemas shared unless a hidden-role schema profile explicitly
     // passes schemaAllowedTools for a small specialist; broad role
     // whitelists would fragment the cache shard.
-    if (resolvedRole && process.env.MIXDOG_DEBUG_SESSION_LOG) {
-        process.stderr.write(`[session] role=${resolvedRole} permission=${permission || 'full'} toolPermission=${toolPermission || 'full'} tools=${tools.length}\n`);
+    if (resolvedAgent && process.env.MIXDOG_DEBUG_SESSION_LOG) {
+        process.stderr.write(`[session] agent=${resolvedAgent} permission=${permission || 'full'} toolPermission=${toolPermission || 'full'} tools=${tools.length}\n`);
     }
     const contextMeta = resolveSessionContextMeta(provider, modelName);
     const workflowMeta = opts.workflow && typeof opts.workflow === 'object' && String(opts.workflow.id || '').trim()
@@ -1758,7 +1773,6 @@ export function createSession(opts) {
         // agent sessions past RUNNING_STALL_MS.
         lastUsedAt: Date.now(),
         tokensCumulative: 0,
-        role: opts.role || null,
         taskType: opts.taskType || null,
         maxLoopIterations: Number.isFinite(opts.maxLoopIterations) ? opts.maxLoopIterations : null,
         // Agent tag (auto worker{n} on spawn) persisted so the forked status
@@ -2203,6 +2217,18 @@ export function usageMetricsIdempotencyKey(sessionId, session, delta = {}) {
     return `${sessionId}:${turnId}:${epoch}:${delta.iterationIndex}:${source}`;
 }
 
+function uncachedInputTokensForProvider(provider, inputTokens, cachedReadTokens = 0, cacheWriteTokens = 0) {
+    const input = Number(inputTokens) || 0;
+    if (input <= 0) return 0;
+    // Anthropic-style providers report input_tokens excluding cache reads; OpenAI
+    // Responses/Gemini-style providers report input_tokens inclusive of cached
+    // prefix tokens. Keep both views so UI can show the real context footprint
+    // and the fresh/new token portion without mistaking cache hits for a cache
+    // break.
+    if (providerInputExcludesCache(provider)) return input + (Number(cacheWriteTokens) || 0);
+    return Math.max(input - (Number(cachedReadTokens) || 0) - (Number(cacheWriteTokens) || 0), 0);
+}
+
 /**
  * Apply terminal ask usage to session totals. Skips lifetime totals when incremental
  * per-iteration persistence already counted this turn (askSession path).
@@ -2211,23 +2237,38 @@ export function applyAskTerminalUsageTotals(session, result, options = {}) {
     if (!session || !result?.usage) return;
     const skipTotals = options.skipTotalsIfIncremental === true;
     if (!skipTotals) {
-        session.totalInputTokens = (session.totalInputTokens || 0) + (result.usage.inputTokens || 0);
-        session.totalOutputTokens = (session.totalOutputTokens || 0) + (result.usage.outputTokens || 0);
+        const inputTokens = result.usage.inputTokens || 0;
+        const outputTokens = result.usage.outputTokens || 0;
+        const cachedTokens = result.usage.cachedTokens || 0;
+        const cacheWriteTokens = result.usage.cacheWriteTokens || 0;
+        const uncachedInputTokens = uncachedInputTokensForProvider(session.provider, inputTokens, cachedTokens, cacheWriteTokens);
+        session.totalInputTokens = (session.totalInputTokens || 0) + inputTokens;
+        session.totalOutputTokens = (session.totalOutputTokens || 0) + outputTokens;
         session.tokensCumulative = (session.tokensCumulative || 0)
-            + (result.usage.inputTokens || 0)
-            + (result.usage.outputTokens || 0);
-        session.totalCachedReadTokens = (session.totalCachedReadTokens || 0) + (result.usage.cachedTokens || 0);
-        session.totalCacheWriteTokens = (session.totalCacheWriteTokens || 0) + (result.usage.cacheWriteTokens || 0);
+            + inputTokens
+            + outputTokens;
+        session.totalCachedReadTokens = (session.totalCachedReadTokens || 0) + cachedTokens;
+        session.totalCacheWriteTokens = (session.totalCacheWriteTokens || 0) + cacheWriteTokens;
+        session.totalUncachedInputTokens = (session.totalUncachedInputTokens || 0) + uncachedInputTokens;
     }
     const _lastTurn = result.lastTurnUsage || result.usage || {};
-    session.lastInputTokens = _lastTurn.inputTokens || 0;
+    const _lastInputTokens = _lastTurn.inputTokens || 0;
+    const _lastCachedReadTokens = _lastTurn.cachedTokens || 0;
+    const _lastCacheWriteTokens = _lastTurn.cacheWriteTokens || 0;
+    session.lastInputTokens = _lastInputTokens;
     session.lastOutputTokens = _lastTurn.outputTokens || 0;
-    session.lastCachedReadTokens = _lastTurn.cachedTokens || 0;
-    session.lastCacheWriteTokens = _lastTurn.cacheWriteTokens || 0;
+    session.lastCachedReadTokens = _lastCachedReadTokens;
+    session.lastCacheWriteTokens = _lastCacheWriteTokens;
+    session.lastUncachedInputTokens = uncachedInputTokensForProvider(
+        session.provider,
+        _lastInputTokens,
+        _lastCachedReadTokens,
+        _lastCacheWriteTokens,
+    );
     const _inputExcludesCache = providerInputExcludesCache(session.provider);
     session.lastContextTokens = _inputExcludesCache
-        ? (_lastTurn.inputTokens || 0) + (_lastTurn.cachedTokens || 0)
-        : (_lastTurn.inputTokens || 0);
+        ? _lastInputTokens + _lastCachedReadTokens + _lastCacheWriteTokens
+        : _lastInputTokens;
     session.lastContextTokensUpdatedAt = Date.now();
     session.lastContextTokensStaleAfterCompact = false;
 }
@@ -2257,6 +2298,9 @@ export async function persistIterationMetrics(delta) {
     seen.add(ikey);
     if (!isReplay) {
         if (runtimeEntry) runtimeEntry.usageMetricsTurnIncremental = true;
+        const deltaUncachedInput = delta.deltaUncachedInput != null
+            ? Number(delta.deltaUncachedInput) || 0
+            : uncachedInputTokensForProvider(session.provider, deltaInput, deltaCachedRead, deltaCacheWrite);
         session.totalInputTokens = (session.totalInputTokens || 0) + (deltaInput || 0);
         session.totalOutputTokens = (session.totalOutputTokens || 0) + (deltaOutput || 0);
         session.tokensCumulative = (session.tokensCumulative || 0) + (deltaInput || 0) + (deltaOutput || 0);
@@ -2266,12 +2310,15 @@ export async function persistIterationMetrics(delta) {
         // includes cached_read / cache_write in its terminal usage rollup).
         session.totalCachedReadTokens = (session.totalCachedReadTokens || 0) + (deltaCachedRead || 0);
         session.totalCacheWriteTokens = (session.totalCacheWriteTokens || 0) + (deltaCacheWrite || 0);
+        session.totalUncachedInputTokens = (session.totalUncachedInputTokens || 0) + deltaUncachedInput;
         // Window snapshot updated per iteration so agent type=list reflects the
         // most-recent provider-reported input size even for short dispatches
         // that finish before askSession's terminal save lands.
         session.lastInputTokens = deltaInput || 0;
         session.lastOutputTokens = deltaOutput || 0;
         session.lastCachedReadTokens = deltaCachedRead || 0;
+        session.lastCacheWriteTokens = deltaCacheWrite || 0;
+        session.lastUncachedInputTokens = deltaUncachedInput;
         // Normalized last-call context footprint: how many prompt tokens the
         // model actually saw on the most-recent send, comparable ACROSS
         // providers. Anthropic reports input_tokens EXCLUDING cache (cache_read
@@ -2280,7 +2327,7 @@ export async function persistIterationMetrics(delta) {
         // tokens INTO the input count, so input alone is the footprint.
         const _inputExcludesCache = providerInputExcludesCache(session.provider);
         session.lastContextTokens = _inputExcludesCache
-            ? (deltaInput || 0) + (deltaCachedRead || 0)
+            ? (deltaInput || 0) + (deltaCachedRead || 0) + (deltaCacheWrite || 0)
             : (deltaInput || 0);
         session.lastContextTokensUpdatedAt = ts || Date.now();
         session.lastContextTokensStaleAfterCompact = false;
@@ -3439,7 +3486,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
                 logLlmCall({
                     ts: new Date().toISOString(),
                     sourceType: session.sourceType || 'lead',
-                    sourceName: session.sourceName || session.role || null,
+                    sourceName: session.sourceName || session.agent || null,
                     preset: session.presetName || null,
                     model: session.model,
                     provider: session.provider,
@@ -3660,13 +3707,13 @@ export async function resumeSession(sessionId, preset) {
     }
     let toolsForRouting = resolveSessionTools(toolSpec, skills, { ownerIsAgentSession: ownerIsAgent });
     if (ownerIsAgent) {
-        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, session.toolPermission, session.role || null);
+        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, session.toolPermission, session.agent || null);
     }
     session.tools = finalizeSessionToolList(toolsForRouting, {
         schemaAllowedTools: Array.isArray(session.schemaAllowedTools) ? session.schemaAllowedTools : null,
-        disallowedTools: null,
+        disallowedTools: getHiddenAgent(session.agent || null) ? ['Skill'] : null,
         ownerIsAgent,
-        resolvedRole: session.role || null,
+        resolvedAgent: session.agent || null,
     });
     const newTools = session.tools;
     const missing = oldTools.filter(t => !newTools.find(n => n.name === t.name));