mixdog 0.9.1 → 0.9.3

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

@@ -1,28 +1,23 @@
 import { classifyResultKind } from './result-classification.mjs';
 import { executeMcpTool, isMcpTool, mcpToolHasField } from '../mcp/client.mjs';
-import { canonicalizeBuiltinToolName, executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool } from '../tools/builtin.mjs';
+import { canonicalizeBuiltinToolName, executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool, isExternalAdapterTool } from '../tools/builtin.mjs';
 import { executeBashSessionTool } from '../tools/bash-session.mjs';
-import { executePatchTool } from '../tools/patch.mjs';
+import { executePatchTool, takeApplyPatchUiDiff } from '../tools/patch.mjs';
 import { executeInternalTool, isInternalTool } from '../internal-tools.mjs';
-import { collectSkillsCached, loadSkillContent } from '../context/collect.mjs';
-import { traceAgentLoop, traceAgentTool, traceAgentToolFailure, traceAgentCompact, estimateProviderPayloadBytes, messagePrefixHash } from '../agent-trace.mjs';
+import { normalizeToolEnvelope, makeToolEnvelope } from './tool-envelope.mjs';
+import { traceAgentLoop, traceAgentTool, traceAgentToolFailure, traceAgentCompact, estimateProviderPayloadBytes, messagePrefixHash, appendAgentTrace } from '../agent-trace.mjs';
+import { resolveSessionMaxLoopIterations } from '../agent-runtime/agent-loop-policy.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
 import { markSessionToolCall, updateSessionStage, SessionClosedError, getSessionAbortSignal, enqueuePendingMessage, bumpUsageMetricsEpoch } from './manager.mjs';
-import { estimateMessagesTokens, estimateRequestReserveTokens, sanitizeToolPairs } from './context-utils.mjs';
 import {
     recallFastTrackCompactMessages,
     pruneToolOutputs,
+    pruneToolOutputsUnanchored,
     semanticCompactMessages,
-    compactTypeIsRecallFastTrack,
-    compactTypeIsSemantic,
-    normalizeCompactType,
+    effectiveBudget as compactEffectiveBudget,
     DEFAULT_COMPACT_TYPE,
-    DEFAULT_COMPACTION_BUFFER_TOKENS,
-    DEFAULT_COMPACTION_BUFFER_RATIO,
-    DEFAULT_COMPACTION_KEEP_TOKENS,
-    compactionBufferTokensForBoundary,
-    normalizeCompactionBufferRatio,
     drainSessionCycle1,
+    countRawPendingRows,
 } from './compact.mjs';
 import { isContextOverflowError } from '../providers/retry-classifier.mjs';
 import { stripSoftWarns } from '../tool-loop-guard.mjs';
@@ -33,26 +28,15 @@ import { modelVisibleToolCompletionMessage } from '../../../shared/tool-executio
 import { createHash } from 'crypto';
 import { isInvalidToolArgsMarker, formatInvalidToolArgsResult } from '../providers/openai-compat-stream.mjs';
 
-// Tool-name classification for cross-turn read dedup.
-// Strips the MCP prefix so direct calls and MCP-wrapped calls share the
-// same cache.
-function _stripMcpPrefix(name) {
-    return typeof name === 'string' && name.startsWith(MCP_TOOL_PREFIX)
-        ? name.slice(MCP_TOOL_PREFIX.length) : name;
-}
-function _isReadTool(name) {
-    return _stripMcpPrefix(name) === 'read';
-}
-function _isMutationTool(name) {
-    const n = _stripMcpPrefix(name);
-    return n === 'apply_patch';
-}
-const SCOPED_CACHEABLE_TOOLS = new Set([
-    'code_graph',
-    'grep',
-    'list',
-    'glob',
-]);
+import {
+    _stripMcpPrefix,
+    _isReadTool,
+    _isMutationTool,
+    _isScopedCacheableTool,
+    _isShellTool,
+    _intraTurnSig,
+} from './loop/tool-classify.mjs';
+import { preDispatchDenyForSession } from './loop/pre-dispatch-deny.mjs';
 let codeGraphRuntimePromise = null;
 async function executeCodeGraphToolLazy(name, args, cwd, signal = null, options = {}) {
     codeGraphRuntimePromise ??= import('../tools/code-graph.mjs');
@@ -60,389 +44,105 @@ async function executeCodeGraphToolLazy(name, args, cwd, signal = null, options
     if (typeof mod.executeCodeGraphTool !== 'function') throw new Error('code_graph runtime is not available');
     return mod.executeCodeGraphTool(name, args, cwd, signal, options);
 }
-function _isScopedCacheableTool(name) {
-    const n = _stripMcpPrefix(name);
-    return SCOPED_CACHEABLE_TOOLS.has(n);
-}
-function _isShellTool(name) {
-    const n = _stripMcpPrefix(name);
-    return n === 'shell' || n === 'bash_session';
-}
 
 // classifyResultKind is imported from result-classification.mjs at the top of
 // this file; import it from there directly rather than via this module.
-
-// Canonical signature for intra-turn duplicate detection. Sorting keys
-// produces a stable hash regardless of arg-object key order. Anything
-// non-serializable falls back to String(args) — still deterministic for
-// the model's typical structured-arg shape.
-function _canonicalArgs(args) {
-    if (args == null || typeof args !== 'object') {
-        try { return JSON.stringify(args); } catch { return String(args); }
-    }
-    try {
-        const keys = Object.keys(args).sort();
-        const sorted = {};
-        for (const k of keys) sorted[k] = args[k];
-        return JSON.stringify(sorted);
-    } catch { return String(args); }
-}
-function _intraTurnSig(name, args) {
-    return createHash('sha256').update(`${name}:${_canonicalArgs(args)}`).digest('hex').slice(0, 16);
-}
-
-// Shared pre-dispatch deny — single source of truth for the remaining
-// control-plane / role scoping rejects. Called by BOTH the eager dispatch
-// path (startEagerTool) and the serial dispatch path (executeTool body).
-// Returns null when the call is allowed to proceed; otherwise returns the
-// Error string the serial path would emit. The eager caller ignores the
-// message body and just treats non-null as "do not start eager".
-//
-// This is NOT a permission gate — runtime permission enforcement was removed
-// (every tool call is trusted). What remains is architectural scoping:
-// agent workers are sandboxed to code/research tools. They must never reach
-// owner/host control surfaces: session management, the ENTIRE channels module
-// (Discord messaging, schedules, webhook/config, channel-bridge toggle,
-// command injection), or host input injection. Explicit name list (no imports)
-// keeps this hot-path gate dependency-free; add new owner/channel tools here.
-const WORKER_DENIED_TOOLS = new Set([
-    // session control-plane — unified into the single `agent` tool
-    // (type=spawn|send|close|list). Denying the one name blocks all worker
-    // session control.
-    'agent',
-    // channels module (owner/Discord-facing)
-    'reply', 'react', 'edit_message', 'download_attachment', 'fetch',
-    'schedule_status', 'trigger_schedule', 'schedule_control',
-    'activate_channel_bridge', 'reload_config', 'inject_command',
-    // host input injection
-    'inject_input',
-]);
-function _preDispatchDeny(call, toolKind, sessionRef) {
-    const name = call?.name;
-    if (typeof name !== 'string' || !name) return null;
-    const _agentOwned = sessionRef?.scope?.startsWith?.('agent:')
-        || isAgentOwner(sessionRef);
-    const _controlPlaneTool = WORKER_DENIED_TOOLS.has(name);
-    if (_agentOwned && _controlPlaneTool) {
-        return `Error: control-plane tool "${name}" is Lead-only and not available to agent workers.`;
-    }
-    const noToolRole = sessionRef?.role === 'cycle1-agent' || sessionRef?.role === 'cycle2-agent';
-    if (noToolRole) {
-        return `Error: tool "${name}" is not available in role "${sessionRef.role}". Re-emit the answer as pipe-separated text per the role's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
-    }
-    return null;
-}
-/** Exported for smoke tests — same runtime deny as the agent loop. */
-export function preDispatchDenyForSession(sessionRef, call, toolKind = 'builtin') {
-    return _preDispatchDeny(call, toolKind, sessionRef);
-}
 import { compressToolResult, recordToolBatch } from '../tools/result-compression.mjs';
 
 
-import { readFileSync as _readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, resolve as resolvePath, isAbsolute } from 'path';
-const MCP_TOOL_PREFIX = 'mcp__plugin_mixdog_mixdog__';
-const COMPACT_SAFETY_PERCENT = 1.00;
-const COMPACT_BUFFER_MAX_WINDOW_FRACTION = 0.25;
-
-function estimateMessagesTokensSafe(messages) {
-    try { return estimateMessagesTokens(messages); }
-    catch { return null; }
-}
-
-function steeringContentText(content) {
-    if (typeof content === 'string') return content;
-    if (Array.isArray(content)) {
-        return content.map((part) => {
-            if (typeof part === 'string') return part;
-            if (part?.type === 'text') return part.text || '';
-            if (part?.type === 'image') return '[Image]';
-            return part?.text || '';
-        }).filter(Boolean).join('\n');
-    }
-    return String(content ?? '');
-}
-
-function normalizeSteeringEntry(entry) {
-    if (typeof entry === 'string') {
-        const text = entry.trim();
-        return text ? { content: text, text } : null;
-    }
-    if (!entry || typeof entry !== 'object') return null;
-    const content = Object.prototype.hasOwnProperty.call(entry, 'content') ? entry.content : entry;
-    const text = typeof entry.text === 'string' ? entry.text.trim() : steeringContentText(content).trim();
-    if (Array.isArray(content)) return content.length > 0 ? { content, text } : null;
-    if (typeof content === 'string') {
-        const value = content.trim();
-        return value ? { content: value, text: text || value } : null;
-    }
-    const fallback = steeringContentText(content).trim();
-    return fallback ? { content: fallback, text: text || fallback } : null;
-}
-
-function mergeSteeringEntries(entries) {
-    const normalized = (Array.isArray(entries) ? entries : [])
-        .map(normalizeSteeringEntry)
-        .filter(Boolean);
-    if (normalized.length === 0) return null;
-    const displayText = normalized.map((entry) => entry.text || steeringContentText(entry.content))
-        .filter((text) => String(text || '').trim())
-        .join('\n');
-    if (normalized.every((entry) => typeof entry.content === 'string')) {
-        return {
-            content: normalized.map((entry) => entry.content).filter(Boolean).join('\n'),
-            text: displayText,
-            count: normalized.length,
-        };
-    }
-    const parts = [];
-    for (const entry of normalized) {
-        if (typeof entry.content === 'string') {
-            if (entry.content.trim()) parts.push({ type: 'text', text: entry.content });
-        } else if (Array.isArray(entry.content)) {
-            parts.push(...entry.content);
-        } else {
-            const text = steeringContentText(entry.content);
-            if (text.trim()) parts.push({ type: 'text', text });
-        }
-        parts.push({ type: 'text', text: '\n' });
-    }
-    while (parts.length && parts[parts.length - 1]?.type === 'text' && parts[parts.length - 1]?.text === '\n') parts.pop();
-    return { content: parts, text: displayText || steeringContentText(parts), count: normalized.length };
-}
-
-class AgentContextOverflowError extends Error {
-    constructor({ stage, sessionId, provider, model, contextWindow, budgetTokens, reserveTokens, messageTokensEst }, cause) {
-        const target = [provider, model].filter(Boolean).join('/') || 'target model';
-        const causeMsg = cause && cause.message ? `: ${cause.message}` : '';
-        super(
-            `agent context overflow (${target}, stage=${stage || 'compact'}): ` +
-            `latest turn cannot fit target context budget=${budgetTokens ?? 'unknown'} ` +
-            `reserve=${reserveTokens ?? 'unknown'} contextWindow=${contextWindow ?? 'unknown'} ` +
-            `messageTokensEst=${messageTokensEst ?? 'unknown'}${causeMsg}`,
-        );
-        this.name = 'AgentContextOverflowError';
-        this.code = 'AGENT_CONTEXT_OVERFLOW';
-        this.sessionId = sessionId || null;
-        this.provider = provider || null;
-        this.model = model || null;
-        this.contextWindow = contextWindow ?? null;
-        this.budgetTokens = budgetTokens ?? null;
-        this.reserveTokens = reserveTokens ?? null;
-        this.messageTokensEst = messageTokensEst ?? null;
-        if (cause) this.cause = cause;
-    }
-}
+import { resolve as resolvePath, isAbsolute } from 'path';
+import {
+    estimateMessagesTokensSafe,
+    compactDiagnosticError,
+    compactByteLength,
+    compactDebugLog,
+} from './loop/compact-debug.mjs';
+import { mergeSteeringEntries, steeringContentText } from './loop/steering.mjs';
+import { agentContextOverflowError } from './loop/context-overflow.mjs';
+import { positiveTokenInt } from './loop/env.mjs';
+import { normalizeUsage, addUsage } from './loop/usage.mjs';
+import { HIDDEN_AGENT_NAMES } from './loop/hidden-agents.mjs';
+import {
+    resolveWorkerCompactPolicy,
+    compactionTelemetryPressureTokens,
+    compactTargetBudget,
+    shouldCompactForSession,
+    countPrunedToolOutputs,
+    rememberCompactTelemetry,
+    emitCompactEvent,
+    compactEventType,
+} from './loop/compact-policy.mjs';
+import {
+    isEagerDispatchable,
+    messagesArrayChanged,
+    getToolKind,
+    buildSkillsListResponse,
+    viewSkill,
+    normalizeHookUpdatedToolOutput,
+    resolveToolResultAfterHook,
+    parseNativeToolSearchPayload,
+    extractBashSessionId,
+    buildAgentBashSessionArgs,
+    formatMissingToolApprovalUiDenial,
+    resolvePreToolAskApproval,
+    approvalGranted,
+    approvalReason,
+} from './loop/tool-helpers.mjs';
+import {
+    compactToolCallsForHistory,
+    restoreToolCallBodyForId,
+} from './loop/stored-tool-args.mjs';
+import { repairTranscriptBeforeProviderSend } from './loop/transcript-repair.mjs';
 
-function agentContextOverflowError({ stage, sessionId, sessionRef, model, budgetTokens, reserveTokens, messageTokensEst }, cause) {
-    return new AgentContextOverflowError({
-        stage,
-        sessionId,
-        provider: sessionRef?.provider || null,
-        model: sessionRef?.model || model || null,
-        contextWindow: sessionRef?.contextWindow ?? null,
-        budgetTokens,
-        reserveTokens,
-        messageTokensEst,
-    }, cause);
-}
+// Facade re-exports: these symbols moved to split modules under ./loop/ but
+// remain part of loop.mjs's public surface (imported by scripts/tests and other
+// runtime modules). Re-export the already-imported local bindings so every
+// existing import path keeps working (no duplicate module binding).
+export {
+    preDispatchDenyForSession,
+    repairTranscriptBeforeProviderSend,
+    normalizeHookUpdatedToolOutput,
+    resolveToolResultAfterHook,
+    buildAgentBashSessionArgs,
+    formatMissingToolApprovalUiDenial,
+    resolvePreToolAskApproval,
+    approvalGranted,
+    approvalReason,
+};
 
-// Cache-hit results always inline the cached body. The earlier size-gated
-// `[cache-hit-ref]` branch confused agents whose context did not
-// contain the referenced prior tool_result, triggering shell-cat detours.
 // Hard iteration ceiling for every agent loop. Reset to 0 whenever the
 // transcript is compacted (see the trim block below): a long task that keeps
 // compacting can proceed past this count, while a tight NON-compacting loop
 // still stops here and returns the accumulated transcript.
-const MAX_LOOP_ITERATIONS = 200;
 // Consecutive identical-AND-failing tool calls (same name+args, error result)
 // tolerated across iterations before the loop refuses to re-execute and steers
 // the model to change approach. Distinct from the hard iteration cap above:
 // this catches tight deterministic-failure loops (e.g. a command that errors
 // the same way every time) far earlier than 100 iterations.
 const REPEAT_FAIL_LIMIT = 3;
-const _HIDDEN_ROLES_JSON = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../defaults/hidden-roles.json');
-let _hiddenRolesCache = null;
-function _getHiddenRoles() {
-    if (_hiddenRolesCache) return _hiddenRolesCache;
-    try {
-        _hiddenRolesCache = JSON.parse(_readFileSync(_HIDDEN_ROLES_JSON, 'utf8'));
-    } catch { _hiddenRolesCache = { roles: [] }; }
-    return _hiddenRolesCache;
-}
-// Transcript pairing guard. Anthropic 400-rejects when an assistant message
-// ends with tool_use blocks and the next message isn't tool results for
-// those exact ids. abort/timeout/error race in the loop body can leave a
-// dangling assistant tool_use at the tail (e.g. the structure_probe loop
-// running 12 deep then aborting between push-assistant and push-tool).
-// Strip any trailing assistant tool_use that has no matching tool result
-// so provider.send sees a valid transcript instead of leaking the 400 to
-// the user. Repair runs every iteration but is a no-op on healthy paths.
-function _ensureTranscriptPairing(msgs, sessionId) {
-    // Walk backwards to find the last assistant message that emitted
-    // tool_use, then validate that every id has a matching tool result
-    // inside the CONTIGUOUS tool-message block immediately following it.
-    // Earlier guard splice'd the entire tail — which silently deleted any
-    // user prompt appended after the dangling assistant by manager.mjs:
-    // when the guard fired with shape
-    //     [..., assistant{a,b}, tool{a}, user{new prompt}]
-    // the splice removed user{new prompt} along with the orphan suffix.
-    // Fix: remove only assistant + the contiguous tool block; preserve
-    // anything past it (user / system / next assistant) untouched.
-    let popped = 0;
-    while (msgs.length > 0) {
-        let lastAssistantIdx = -1;
-        for (let i = msgs.length - 1; i >= 0; i--) {
-            const m = msgs[i];
-            if (m?.role === 'assistant' && Array.isArray(m.toolCalls) && m.toolCalls.length > 0) {
-                lastAssistantIdx = i;
-                break;
-            }
-        }
-        if (lastAssistantIdx === -1) break;
-        // Collect the contiguous tool messages directly after this assistant.
-        // Anything past that block is unrelated (next user prompt, system
-        // marker, etc.) and must survive the repair.
-        let toolBlockEnd = lastAssistantIdx + 1;
-        while (toolBlockEnd < msgs.length && msgs[toolBlockEnd]?.role === 'tool') {
-            toolBlockEnd += 1;
-        }
-        const toolBlock = msgs.slice(lastAssistantIdx + 1, toolBlockEnd);
-        const ids = msgs[lastAssistantIdx].toolCalls.map(c => c.id);
-        const matched = ids.every(id => toolBlock.some(m => m.toolCallId === id));
-        if (matched) break;
-        const removed = toolBlockEnd - lastAssistantIdx;
-        msgs.splice(lastAssistantIdx, removed);
-        popped += removed;
-    }
-    // Second sweep — catch dangling tool results that survived the
-    // contiguous-block splice. Anthropic strict spec requires every
-    // tool result to sit in a contiguous block right after the
-    // assistant whose toolCalls produced it; a `[..., assistant{a,b},
-    // tool{a}, user, tool{b}]` shape leaves tool{b} orphaned even
-    // after assistant + tool{a} are repaired by the loop above.
-    // Walk back from each tool message to the nearest non-tool
-    // ancestor; if it is not an assistant whose toolCalls include
-    // this id, drop the orphan.
-    for (let i = msgs.length - 1; i >= 0; i--) {
-        const m = msgs[i];
-        if (m?.role !== 'tool') continue;
-        if (!m.toolCallId) {
-            msgs.splice(i, 1);
-            popped += 1;
-            continue;
-        }
-        let prevIdx = i - 1;
-        while (prevIdx >= 0 && msgs[prevIdx]?.role === 'tool') prevIdx--;
-        const anchor = prevIdx >= 0 ? msgs[prevIdx] : null;
-        const anchorOk = anchor?.role === 'assistant'
-            && Array.isArray(anchor.toolCalls)
-            && anchor.toolCalls.some(c => c.id === m.toolCallId);
-        if (!anchorOk) {
-            msgs.splice(i, 1);
-            popped += 1;
-        }
-    }
-    if (popped > 0 && sessionId) {
-        try { process.stderr.write(`[transcript-repair] sess=${sessionId} popped=${popped} dangling assistant tool_use\n`); } catch {}
-    }
-}
-
-/**
- * Pre-provider transcript repair for the agent loop. Reattach valid tool
- * results (non-destructive) before any destructive orphan pairing cleanup.
- * Mutates `messages` in place to preserve the session array reference.
- */
-export function repairTranscriptBeforeProviderSend(messages, sessionId = null) {
-    if (!Array.isArray(messages)) return messages;
-    const sanitized = sanitizeToolPairs(messages);
-    if (sanitized !== messages) {
-        messages.length = 0;
-        messages.push(...sanitized);
-    }
-    _ensureTranscriptPairing(messages, sessionId);
-    return messages;
-}
-
-// Eager-dispatch: tools with readOnlyHint:true in their declaration are safe
-// to execute during SSE parsing so tool work overlaps with the rest of the
-// stream. Writes, bash, MCP and skills stay serial after send() returns.
-function isEagerDispatchable(name, tools) {
-    if (!Array.isArray(tools)) return false;
-    const def = tools.find(t => t?.name === name);
-    return def?.annotations?.readOnlyHint === true;
-}
-function messagesArrayChanged(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;
-}
-function normalizeUsage(usage) {
-    if (!usage) return null;
-    const costUsd = Number(usage.costUsd);
-    return {
-        inputTokens: usage.inputTokens || 0,
-        outputTokens: usage.outputTokens || 0,
-        cachedTokens: usage.cachedTokens || 0,
-        cacheWriteTokens: usage.cacheWriteTokens || 0,
-        promptTokens: usage.promptTokens || 0,
-        ...(Number.isFinite(costUsd) ? { costUsd } : {}),
-        raw: usage.raw,
-    };
-}
-function addUsage(total, usage) {
-    const delta = normalizeUsage(usage);
-    if (!delta) return total;
-    if (!total) return { ...delta };
-    const next = {
-        ...total,
-        inputTokens: (total.inputTokens || 0) + delta.inputTokens,
-        outputTokens: (total.outputTokens || 0) + delta.outputTokens,
-        cachedTokens: (total.cachedTokens || 0) + delta.cachedTokens,
-        cacheWriteTokens: (total.cacheWriteTokens || 0) + delta.cacheWriteTokens,
-        promptTokens: (total.promptTokens || 0) + delta.promptTokens,
-    };
-    if (delta.costUsd != null || total.costUsd != null) {
-        next.costUsd = (total.costUsd || 0) + (delta.costUsd || 0);
-    }
-    return next;
-}
-function positiveTokenInt(value) {
-    const n = Number(value);
-    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
-}
-function envFlag(name, fallback = false) {
-    const v = process.env[name];
-    if (v === undefined) return fallback;
-    return !['0', 'false', 'off', 'no'].includes(String(v).trim().toLowerCase());
-}
-function envTokenInt(name) {
-    return positiveTokenInt(process.env[name]);
-}
-function resolveSemanticCompactSetting(sessionRef, cfg = {}) {
-    if (process.env.MIXDOG_AGENT_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_AGENT_COMPACT_SEMANTIC', true);
-    if (cfg.semantic === false || cfg.semantic === 'false' || cfg.semantic === 'off') return false;
-    if (cfg.semantic === true || cfg.semantic === 'true' || cfg.semantic === 'on') return true;
-    // The compact type is already explicit (`semantic` by default). Honor it
-    // directly instead of substituting another compaction path.
-    return true;
-}
-
-function resolveCompactTypeSetting(_sessionRef, cfg = {}) {
-    const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
-        ?? process.env.MIXDOG_COMPACT_TYPE
-        ?? cfg.type
-        ?? cfg.compactType
-        ?? cfg.compact_type;
-    return normalizeCompactType(configured, DEFAULT_COMPACT_TYPE);
-}
-
 async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTokens, compactPolicy, sessionId, signal }) {
     if (!sessionId) throw new Error('recall-fasttrack requires a session id');
+    const startedAt = Date.now();
+    const diagnostics = {
+        hydrateLimit: null,
+        ingestMs: null,
+        ingestSkipped: false,
+        ingestError: null,
+        initialDumpMs: null,
+        initialDumpBytes: null,
+        initialDumpChars: null,
+        initialRawPending: null,
+        cycle1Ms: null,
+        cycle1Skipped: false,
+        cycle1SkipReason: null,
+        cycle1Passes: null,
+        cycle1RawRemaining: null,
+        cycle1TextBytes: null,
+        cycle1Error: null,
+        finalRecallBytes: null,
+        finalRecallChars: null,
+        totalMs: null,
+    };
     const query = `session:${sessionId}:all-chunks`;
     const querySha = createHash('sha256').update(query).digest('hex').slice(0, 16);
     const callerCtx = {
@@ -454,6 +154,8 @@ async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTo
     };
     const hydrateLimit = positiveTokenInt(sessionRef?.compaction?.recallIngestLimit)
         || Math.max(500, Math.min(5000, messages.length || 0));
+    diagnostics.hydrateLimit = hydrateLimit;
+    let t0 = Date.now();
     try {
         await executeInternalTool('memory', {
             action: 'ingest_session',
@@ -463,7 +165,11 @@ async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTo
             limit: hydrateLimit,
         }, callerCtx);
     } catch (err) {
+        diagnostics.ingestSkipped = true;
+        diagnostics.ingestError = compactDiagnosticError(err);
         try { process.stderr.write(`[loop] recall-fasttrack ingest skipped (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
+    } finally {
+        diagnostics.ingestMs = Date.now() - t0;
     }
     const dumpArgs = {
         action: 'dump_session_roots',
@@ -472,10 +178,16 @@ async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTo
         limit: positiveTokenInt(sessionRef?.compaction?.recallChunkLimit ?? sessionRef?.compaction?.recallLimit) || hydrateLimit,
     };
     const runTool = (name, args) => executeInternalTool(name, args, callerCtx);
+    t0 = Date.now();
     let recallText = await executeInternalTool('memory', dumpArgs, callerCtx);
+    diagnostics.initialDumpMs = Date.now() - t0;
+    diagnostics.initialDumpChars = String(recallText || '').length;
+    diagnostics.initialDumpBytes = compactByteLength(recallText);
+    diagnostics.initialRawPending = countRawPendingRows(recallText);
     let cycle1Text = '';
     const hasRawRows = /(?:^|\n)# raw_pending\s+\d+\s+id=/i.test(String(recallText || ''));
     if (hasRawRows) {
+        t0 = Date.now();
         try {
             // Drain this session's cycle1 in window×concurrency units until no
             // raw rows remain, so the injected root is fully chunked rather than
@@ -496,19 +208,32 @@ async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTo
             });
             recallText = drained.recallText;
             cycle1Text = drained.cycle1Text;
+            diagnostics.cycle1Passes = drained.passes;
+            diagnostics.cycle1RawRemaining = drained.rawRemaining;
+            diagnostics.cycle1TextBytes = compactByteLength(cycle1Text);
             if (drained.rawRemaining > 0) {
                 try { process.stderr.write(`[loop] recall-fasttrack drained passes=${drained.passes} rawRemaining=${drained.rawRemaining} (sess=${sessionId || 'unknown'})\n`); } catch {}
             }
         } catch (err) {
+            diagnostics.cycle1Error = compactDiagnosticError(err);
             try { process.stderr.write(`[loop] recall-fasttrack cycle1 skipped (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
+        } finally {
+            diagnostics.cycle1Ms = Date.now() - t0;
         }
     } else {
+        diagnostics.cycle1Skipped = true;
+        diagnostics.cycle1SkipReason = 'session chunks already hydrated';
+        diagnostics.cycle1Passes = 0;
+        diagnostics.cycle1RawRemaining = 0;
         cycle1Text = 'cycle1: skipped (session chunks already hydrated)';
     }
-    return recallFastTrackCompactMessages(messages, compactBudgetTokens, {
+    const combinedRecallText = [`session_id=${sessionId}`, cycle1Text, recallText].map(v => String(v || '').trim()).filter(Boolean).join('\n\n');
+    diagnostics.finalRecallChars = combinedRecallText.length;
+    diagnostics.finalRecallBytes = compactByteLength(combinedRecallText);
+    const result = recallFastTrackCompactMessages(messages, compactBudgetTokens, {
         reserveTokens: compactPolicy.reserveTokens,
         force: true,
-        recallText: [`session_id=${sessionId}`, cycle1Text, recallText].map(v => String(v || '').trim()).filter(Boolean).join('\n\n'),
+        recallText: combinedRecallText,
         query,
         querySha,
         allowEmptyRecall: true,
@@ -516,562 +241,16 @@ async function runRecallFastTrackCompact({ sessionRef, messages, compactBudgetTo
         keepTokens: compactPolicy.keepTokens,
         preserveRecentTokens: compactPolicy.preserveRecentTokens,
     });
-}
-// Percent-named inputs (bufferPercent / bufferPct / *_BUFFER_PERCENT) carry a
-// PERCENT: 1 means 1% (0.01). Ratio-named inputs (bufferRatio / bufferFraction)
-// carry a fraction: 0.01 means 1%, and a legacy value > 1 is read as a percent
-// (10 -> 10%). The shared normalizeCompactionBufferRatio only handles the ratio
-// convention, so resolve percent-named values to a fraction first.
-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 resolveCompactBufferRatio(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);
-}
-const LEGACY_DEFAULT_COMPACTION_BUFFER_RATIO = 0.1;
-function isPersistedZeroBufferTelemetry(cfg = {}, boundaryTokens = 0) {
-    const boundary = positiveTokenInt(boundaryTokens);
-    if (!boundary) return false;
-    if (envTokenInt('MIXDOG_AGENT_COMPACT_BUFFER_TOKENS')) return false;
-    for (const envName of ['MIXDOG_AGENT_COMPACT_BUFFER_PERCENT', 'MIXDOG_AGENT_COMPACT_BUFFER_RATIO']) {
-        const n = Number(process.env[envName]);
-        if (Number.isFinite(n) && n > 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 = positiveTokenInt(boundaryTokens);
-    if (!boundary) return false;
-    if (envTokenInt('MIXDOG_AGENT_COMPACT_BUFFER_TOKENS')) return false;
-    for (const envName of ['MIXDOG_AGENT_COMPACT_BUFFER_PERCENT', 'MIXDOG_AGENT_COMPACT_BUFFER_RATIO']) {
-        const n = Number(process.env[envName]);
-        if (Number.isFinite(n) && n > 0) return false;
-    }
-    // Percent/fraction-named fields are operator config. The legacy default
-    // telemetry persisted bufferTokens + bufferRatio after a check/compact pass.
-    for (const key of ['bufferPercent', 'bufferPct', 'bufferFraction']) {
-        const n = Number(cfg?.[key]);
-        if (Number.isFinite(n) && n > 0) return false;
-    }
-    const explicitTokens = positiveTokenInt(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 = positiveTokenInt(cfg?.boundaryTokens);
-    const cfgTrigger = positiveTokenInt(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 resolveCompactBufferTokens(boundaryTokens, cfg = {}) {
-    const boundary = positiveTokenInt(boundaryTokens);
-    const effectiveCfg = compactBufferConfigForBoundary(cfg, boundary);
-    const configured = positiveTokenInt(effectiveCfg.bufferTokens ?? effectiveCfg.buffer)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_BUFFER_TOKENS')
-        || 0;
-    if (!boundary) return configured || DEFAULT_COMPACTION_BUFFER_TOKENS;
-    return compactionBufferTokensForBoundary(boundary, {
-        explicitTokens: configured,
-        ratio: resolveCompactBufferRatio(effectiveCfg),
-        maxRatio: COMPACT_BUFFER_MAX_WINDOW_FRACTION,
-    });
-}
-const COMPACT_TARGET_RATIO = 0.02;
-const COMPACT_TARGET_MIN_TOKENS = 4_000;
-const COMPACT_TARGET_MAX_TOKENS = 16_000;
-function resolveCompactTargetRatio(cfg = {}) {
-    const raw = cfg.targetPercent
-        ?? cfg.targetPct
-        ?? cfg.targetRatio
-        ?? cfg.targetFraction
-        ?? process.env.MIXDOG_AGENT_COMPACT_TARGET_PERCENT
-        ?? process.env.MIXDOG_COMPACT_TARGET_PERCENT
-        ?? COMPACT_TARGET_RATIO;
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0) return COMPACT_TARGET_RATIO;
-    return n > 1 ? n / 100 : n;
-}
-function resolveCompactTargetTokens(boundaryTokens, cfg = {}) {
-    const boundary = positiveTokenInt(boundaryTokens);
-    if (!boundary) return null;
-    const explicit = positiveTokenInt(cfg.targetTokens ?? cfg.target)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_TOKENS')
-        || envTokenInt('MIXDOG_COMPACT_TARGET_TOKENS');
-    if (explicit) return Math.max(1, Math.min(boundary, explicit));
-    const minTarget = Math.min(boundary, positiveTokenInt(cfg.targetMinTokens ?? cfg.minTargetTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MIN_TOKENS')
-        || envTokenInt('MIXDOG_COMPACT_TARGET_MIN_TOKENS')
-        || COMPACT_TARGET_MIN_TOKENS);
-    const maxTarget = Math.min(boundary, positiveTokenInt(cfg.targetMaxTokens ?? cfg.maxTargetTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MAX_TOKENS')
-        || envTokenInt('MIXDOG_COMPACT_TARGET_MAX_TOKENS')
-        || COMPACT_TARGET_MAX_TOKENS);
-    const byRatio = Math.max(1, Math.floor(boundary * resolveCompactTargetRatio(cfg)));
-    return Math.max(1, Math.min(boundary, maxTarget, Math.max(minTarget, byRatio)));
-}
-function resolveCompactKeepTokens(cfg = {}) {
-    return positiveTokenInt(cfg.keepTokens ?? cfg.keep?.tokens ?? cfg.preserveRecentTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_KEEP_TOKENS')
-        || DEFAULT_COMPACTION_KEEP_TOKENS;
-}
-function resolveWorkerCompactPolicy(sessionRef, tools) {
-    if (!sessionRef) return null;
-    const cfg = sessionRef.compaction || {};
-    const auto = cfg.auto !== false && envFlag('MIXDOG_AGENT_COMPACT_AUTO', true);
-    if (!auto) return { auto: false };
-    const contextWindow = positiveTokenInt(sessionRef.contextWindow ?? cfg.contextWindow);
-    const explicitBoundary = positiveTokenInt(sessionRef.compactBoundaryTokens ?? cfg.boundaryTokens);
-    const autoLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit ?? cfg.autoCompactTokenLimit);
-    const boundaryTokens = explicitBoundary && contextWindow
-        ? Math.min(explicitBoundary, contextWindow)
-        : (explicitBoundary || contextWindow || autoLimit);
-    if (!boundaryTokens) return null;
-    const compactBoundaryTokens = Math.max(1, Math.floor(boundaryTokens * COMPACT_SAFETY_PERCENT));
-    // Only an explicit auto-compact limit STRICTLY BELOW the boundary acts as
-    // the trigger. A persisted value == boundary (legacy derived full-window
-    // autoCompactTokenLimit) would set autoTriggerTokens == boundary and
-    // collapse/override the default trigger, so it is ignored in favor of the
-    // default boundary trigger.
-    const autoTriggerTokens = autoLimit && autoLimit < compactBoundaryTokens ? Math.max(1, autoLimit) : null;
-    // Sanitized explicit limit: only a sub-boundary value is a real auto-compact
-    // limit. Anything >= boundary is a legacy derived full-window artifact and
-    // is reported as null so rememberCompactTelemetry does not re-persist it
-    // back onto the session and re-collapse the buffer on the next turn.
-    const explicitAutoCompactTokenLimit = autoTriggerTokens;
-    const bufferTokens = autoTriggerTokens
-        ? Math.max(0, compactBoundaryTokens - autoTriggerTokens)
-        : resolveCompactBufferTokens(compactBoundaryTokens, cfg);
-    const bufferRatio = compactBoundaryTokens ? (bufferTokens / compactBoundaryTokens) : resolveCompactBufferRatio(cfg);
-    const triggerTokens = autoTriggerTokens || Math.max(1, compactBoundaryTokens - bufferTokens);
-    const configuredReserve = positiveTokenInt(cfg.reservedTokens)
-        || envTokenInt('MIXDOG_AGENT_COMPACT_RESERVED_TOKENS')
-        || 0;
-    const requestReserve = estimateRequestReserveTokens(tools);
-    const keepTokens = resolveCompactKeepTokens(cfg);
-    const compactType = resolveCompactTypeSetting(sessionRef, cfg);
-    return {
-        auto: true,
-        type: compactType,
-        compactType,
-        prune: cfg.prune === true || envFlag('MIXDOG_AGENT_COMPACT_PRUNE', false),
-        boundaryTokens: compactBoundaryTokens,
-        triggerTokens,
-        bufferTokens,
-        bufferRatio,
-        contextWindow,
-        rawContextWindow: positiveTokenInt(sessionRef.rawContextWindow ?? cfg.rawContextWindow) || contextWindow,
-        effectiveContextWindowPercent: Number.isFinite(Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent))
-            ? Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent)
-            : null,
-        autoCompactTokenLimit: explicitAutoCompactTokenLimit,
-        semantic: compactTypeIsSemantic(compactType) && resolveSemanticCompactSetting(sessionRef, cfg),
-        recallFastTrack: compactTypeIsRecallFastTrack(compactType),
-        semanticTimeoutMs: positiveTokenInt(cfg.timeoutMs) || envTokenInt('MIXDOG_AGENT_COMPACT_TIMEOUT_MS') || 30_000,
-        tailTurns: positiveTokenInt(cfg.tailTurns) || envTokenInt('MIXDOG_AGENT_COMPACT_TAIL_TURNS') || 2,
-        keepTokens,
-        preserveRecentTokens: positiveTokenInt(cfg.preserveRecentTokens) || envTokenInt('MIXDOG_AGENT_COMPACT_PRESERVE_RECENT_TOKENS') || keepTokens,
-        reserveTokens: requestReserve + configuredReserve,
-        requestReserveTokens: requestReserve,
-        configuredReserveTokens: configuredReserve,
-    };
-}
-/** Transcript + request reserve only (never provider lastContextTokens). */
-function compactPressureTokens(messageTokensEst, policy) {
-    if (messageTokensEst === null) return 0;
-    return Math.max(0, messageTokensEst + (policy?.reserveTokens || 0));
-}
-
-/** Telemetry pressure when a reactive overflow retry forces the next compact. */
-function compactionTelemetryPressureTokens(messageTokensEst, policy, { reactivePending = false } = {}) {
-    const base = compactPressureTokens(messageTokensEst, policy);
-    if (!reactivePending) return base;
-    const floor = positiveTokenInt(policy?.triggerTokens) || positiveTokenInt(policy?.boundaryTokens) || 0;
-    return floor ? Math.max(base, floor) : base;
-}
-function compactTargetBudget(policy) {
-    const boundary = positiveTokenInt(policy?.boundaryTokens);
-    if (!boundary) return null;
-    const reserve = Math.max(0, Number(policy?.reserveTokens) || 0);
-    const targetEffective = resolveCompactTargetTokens(boundary, policy) || boundary;
-    return Math.max(1, Math.min(boundary, targetEffective + reserve));
-}
-function shouldCompactForSession(messageTokensEst, policy, { forceReactive = false } = {}) {
-    if (!policy?.auto || !policy.boundaryTokens) return false;
-    if (forceReactive) return true;
-    if (messageTokensEst === null) return true;
-    return compactPressureTokens(messageTokensEst, policy) >= (policy.triggerTokens || policy.boundaryTokens);
-}
-function countPrunedToolOutputs(before, after) {
-    if (!Array.isArray(before) || !Array.isArray(after)) return 0;
-    let count = 0;
-    const n = Math.min(before.length, after.length);
-    for (let i = 0; i < n; i += 1) {
-        if (before[i]?.role !== 'tool' || after[i]?.role !== 'tool') continue;
-        if (before[i]?.content !== after[i]?.content && after[i]?.compactedKind === 'tool_output_prune') count += 1;
-    }
-    return count;
-}
-function rememberCompactTelemetry(sessionRef, policy, meta = {}) {
-    if (!sessionRef || !policy) return;
-    const prev = sessionRef.compaction && typeof sessionRef.compaction === 'object'
-        ? sessionRef.compaction
-        : {};
-    const changed = meta.compactChanged === true || meta.pruneCount > 0;
-    sessionRef.compaction = {
-        ...prev,
-        auto: policy.auto !== false,
-        prune: policy.prune === true,
-        reservedTokens: policy.configuredReserveTokens || prev.reservedTokens || null,
-        requestReserveTokens: policy.requestReserveTokens || 0,
-        reserveTokens: policy.reserveTokens || 0,
-        boundaryTokens: policy.boundaryTokens || null,
-        triggerTokens: policy.triggerTokens || null,
-        bufferTokens: policy.bufferTokens || 0,
-        bufferRatio: policy.bufferRatio ?? prev.bufferRatio ?? null,
-        contextWindow: policy.contextWindow || null,
-        rawContextWindow: policy.rawContextWindow || null,
-        effectiveContextWindowPercent: policy.effectiveContextWindowPercent ?? null,
-        autoCompactTokenLimit: policy.autoCompactTokenLimit || null,
-        type: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
-        compactType: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
-        semantic: policy.semantic === true ? 'auto' : false,
-        recallFastTrack: policy.recallFastTrack === true,
-        semanticModel: policy.semanticModel || null,
-        semanticTimeoutMs: policy.semanticTimeoutMs || null,
-        tailTurns: policy.tailTurns || null,
-        keepTokens: policy.keepTokens || null,
-        preserveRecentTokens: policy.preserveRecentTokens || null,
-        lastCheckedAt: Date.now(),
-        lastBeforeTokens: meta.beforeTokens ?? null,
-        lastAfterTokens: meta.afterTokens ?? null,
-        lastPressureTokens: meta.pressureTokens ?? null,
-        currentEstimatedTokens: meta.pressureTokens ?? prev.currentEstimatedTokens ?? null,
-        lastApiRequestTokens: positiveTokenInt(sessionRef?.lastContextTokens) || prev.lastApiRequestTokens || null,
-        lastStage: meta.stage || prev.lastStage || null,
-        lastChanged: changed,
-        lastTrigger: meta.trigger || prev.lastTrigger || null,
-        lastSemantic: meta.semanticCompact === true,
-        lastSemanticError: Object.hasOwn(meta, 'semanticError')
-            ? (meta.semanticError ?? null)
-            : (prev.lastSemanticError ?? null),
-        lastRecallFastTrack: meta.recallFastTrack === true,
-        lastRecallFastTrackError: Object.hasOwn(meta, 'recallFastTrackError')
-            ? (meta.recallFastTrackError ?? null)
-            : (prev.lastRecallFastTrackError ?? null),
-        lastError: Object.hasOwn(meta, 'compactError') || Object.hasOwn(meta, 'lastError')
-            ? (meta.compactError ?? meta.lastError ?? null)
-            : (prev.lastError ?? null),
-        lastPruneCount: meta.pruneCount || 0,
-        lastDurationMs: meta.durationMs != null && Number.isFinite(Number(meta.durationMs))
-            ? Math.max(0, Math.round(Number(meta.durationMs)))
-            : null,
-        compactCount: (prev.compactCount || 0) + (changed ? 1 : 0),
-    };
-    if (changed) {
-        const changedAt = Date.now();
-        sessionRef.compaction.lastChangedAt = changedAt;
-        sessionRef.compaction.lastCompactAt = changedAt;
-        sessionRef.lastContextTokensStaleAfterCompact = true;
-    }
-    sessionRef.contextWindow = policy.contextWindow || sessionRef.contextWindow;
-    sessionRef.rawContextWindow = policy.rawContextWindow || sessionRef.rawContextWindow;
-    sessionRef.compactBoundaryTokens = policy.boundaryTokens || sessionRef.compactBoundaryTokens || null;
-    // Persist only the sanitized (sub-boundary) explicit limit. policy.autoCompactTokenLimit
-    // is already null for legacy derived full-window values, so a stale
-    // boundary-sized autoCompactTokenLimit on the session is cleared here rather
-    // than carried forward to re-collapse the buffer next turn.
-    {
-        const _boundary = positiveTokenInt(sessionRef.compactBoundaryTokens);
-        const _prevLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit);
-        const _keepPrev = _prevLimit && (!_boundary || _prevLimit < _boundary) ? _prevLimit : null;
-        sessionRef.autoCompactTokenLimit = policy.autoCompactTokenLimit || _keepPrev || null;
-    }
-    if (policy.effectiveContextWindowPercent !== null) {
-        sessionRef.effectiveContextWindowPercent = policy.effectiveContextWindowPercent;
-    }
-}
-
-function emitCompactEvent(opts, event = {}) {
-    if (!opts || typeof opts.onCompactEvent !== 'function') return;
-    try { opts.onCompactEvent({ ts: Date.now(), ...event }); }
-    catch { /* best-effort UI/log hook */ }
-}
-
-function compactEventType(policy, fallback = DEFAULT_COMPACT_TYPE) {
-    return policy?.compactType || policy?.type || fallback;
-}
-const SKILL_TOOL_NAMES = new Set(['Skill', 'skills_list', 'skill_view']);
-const SPECIAL_TOOL_NAMES = new Set(['bash_session', 'apply_patch', 'code_graph']);
-const BASH_SESSION_HEADER_RE = /\[session: ([^\]\r\n]+)\]/;
-const STORED_TOOL_ARG_BODY_KEY_RE = /^(?:content|old_string|new_string|patch|rewrite)$/i;
-const STORED_TOOL_ARG_LONG_KEY_RE = /^(?:command|script)$/i;
-const STORED_TOOL_ARG_BODY_LIMIT = 2_000;
-const STORED_TOOL_ARG_LONG_LIMIT = 8_000;
-const STORED_TOOL_ARG_PREVIEW_HEAD = 360;
-const STORED_TOOL_ARG_PREVIEW_TAIL = 160;
-
-function compactStoredToolArgString(value, key = '') {
-    if (typeof value !== 'string') return value;
-    const isBody = STORED_TOOL_ARG_BODY_KEY_RE.test(key);
-    const isLong = isBody || STORED_TOOL_ARG_LONG_KEY_RE.test(key);
-    const limit = isBody ? STORED_TOOL_ARG_BODY_LIMIT : (isLong ? STORED_TOOL_ARG_LONG_LIMIT : Infinity);
-    if (value.length <= limit) return value;
-    const hash = createHash('sha256').update(value).digest('hex').slice(0, 16);
-    const head = value.slice(0, STORED_TOOL_ARG_PREVIEW_HEAD).replace(/\r\n/g, '\n');
-    const tail = value.slice(-STORED_TOOL_ARG_PREVIEW_TAIL).replace(/\r\n/g, '\n');
-    return `[mixdog compacted ${key || 'string'}: ${value.length} chars, sha256:${hash}]\n${head}\n... [middle omitted from stored tool-call args] ...\n${tail}`;
-}
-
-function compactStoredToolArgValue(value, key = '', depth = 0) {
-    if (value === null || value === undefined) return value;
-    if (typeof value === 'string') return compactStoredToolArgString(value, key);
-    if (typeof value !== 'object') return value;
-    if (depth >= 6) return Array.isArray(value) ? `[${value.length} items]` : '{...}';
-    if (Array.isArray(value)) {
-        return value.map((item) => compactStoredToolArgValue(item, key, depth + 1));
-    }
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-        out[k] = compactStoredToolArgValue(v, k, depth + 1);
-    }
-    return out;
-}
-
-function compactToolCallsForHistory(calls) {
-    if (!Array.isArray(calls)) return calls;
-    return calls.map((call) => {
-        if (!call || typeof call !== 'object') return call;
-        return {
-            ...call,
-            arguments: compactStoredToolArgValue(call.arguments),
-        };
-    });
-}
-
-// Restore the FULL body of ONE tool call inside a history assistant message
-// whose toolCalls were compacted at push time. Used for a failed edit call so
-// the model sees the original patch/old_string on retry instead of a
-// `[mixdog compacted …]` placeholder it cannot act on. Must run BEFORE the
-// message is first transmitted so it never mutates an already-cached prefix
-// (the prompt cache is content-prefix matched).
-//
-// Only the compactable body/long keys (patch, old_string, new_string, content,
-// rewrite, command, script) are restored, and at ANY depth — compaction is
-// recursive (compactStoredToolArgValue), so batch shapes like edits[].old_string
-// or writes[].content carry nested compacted bodies too. Every other field
-// (e.g. `path`, which a tool may mutate in place during execution) is taken from
-// the compacted snapshot captured at push time, before any mutation. The
-// compacted args tree is built fresh by compactToolCallsForHistory and is not
-// shared with originalCalls, so rebuilding it here is safe.
-function restoreToolCallBodyForId(assistantMsg, originalCalls, callId) {
-    if (!assistantMsg || !Array.isArray(assistantMsg.toolCalls) || !callId) return;
-    if (!Array.isArray(originalCalls)) return;
-    const tc = assistantMsg.toolCalls.find((t) => t && t.id === callId);
-    const orig = originalCalls.find((c) => c && c.id === callId);
-    if (!tc || !orig) return;
-    if (!tc.arguments || typeof tc.arguments !== 'object'
-        || !orig.arguments || typeof orig.arguments !== 'object') return;
-    tc.arguments = _restoreCompactedBodies(tc.arguments, orig.arguments, '');
-}
-
-// Recursively rebuild a compacted args tree: replace ONLY compactable body/long
-// string fields (matched by key at any depth) with their full originals, and
-// keep every other field from the compacted snapshot. tcVal and origVal share
-// the same structure (compaction only shortens body strings), so the walk
-// descends them in parallel; a missing or non-object origVal falls back to the
-// compacted value rather than throwing.
-function _restoreCompactedBodies(tcVal, origVal, key) {
-    if ((STORED_TOOL_ARG_BODY_KEY_RE.test(key) || STORED_TOOL_ARG_LONG_KEY_RE.test(key))
-        && typeof origVal === 'string') {
-        return origVal;
-    }
-    if (Array.isArray(tcVal) && Array.isArray(origVal)) {
-        return tcVal.map((item, i) => _restoreCompactedBodies(item, origVal[i], key));
-    }
-    if (tcVal && typeof tcVal === 'object' && origVal && typeof origVal === 'object') {
-        const out = {};
-        for (const k of Object.keys(tcVal)) {
-            out[k] = (k in origVal) ? _restoreCompactedBodies(tcVal[k], origVal[k], k) : tcVal[k];
-        }
-        return out;
-    }
-    return tcVal;
-}
-/**
- * Execute a single tool call — routes to MCP or builtin.
- */
-function getToolKind(name) {
-    if (SKILL_TOOL_NAMES.has(name)) return 'skill';
-    if (SPECIAL_TOOL_NAMES.has(name)) return 'builtin';
-    if (isMcpTool(name)) return 'mcp';
-    if (isInternalTool(name)) return 'internal';
-    if (isBuiltinTool(name)) return 'builtin';
-    return 'builtin';
-}
-function buildSkillsListResponse(cwd) {
-    const skills = collectSkillsCached(cwd);
-    const entries = skills.map(s => ({ name: s.name, description: s.description || '' }));
-    return JSON.stringify({ skills: entries });
-}
-function viewSkill(cwd, name) {
-    if (!name) return 'Error: skill name is required';
-    const content = loadSkillContent(name, cwd);
-    if (!content) return `Error: skill "${name}" not found`;
-    return `<skill>\n<name>${String(name).replace(/[<>&]/g, (ch) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' }[ch]))}</name>\n${content}\n</skill>`;
-}
-
-/** Normalize PostToolUse hook override values (legacy MCP text envelopes only). */
-export function normalizeHookUpdatedToolOutput(value) {
-    if (typeof value === 'string') return value;
-    if (value == null) return '';
-    if (typeof value === 'object' && Array.isArray(value.content)) {
-        const hasNonText = value.content.some((c) => c && typeof c === 'object' && c.type && c.type !== 'text');
-        if (hasNonText) return value;
-        return value.content
-            .map((c) => (c?.type === 'text' ? c.text || '' : JSON.stringify(c)))
-            .join('\n');
-    }
-    return value;
-}
-
-export function resolveToolResultAfterHook(originalResult, hookResult) {
-    if (!hookResult || typeof hookResult !== 'object' || hookResult.updatedToolOutput === undefined) {
-        return originalResult;
-    }
-    const updated = normalizeHookUpdatedToolOutput(hookResult.updatedToolOutput);
-    return updated === undefined ? originalResult : updated;
-}
-
-function parseNativeToolSearchPayload(toolName, result) {
-    if (toolName !== 'tool_search' || typeof result !== 'string') return null;
-    try {
-        const parsed = JSON.parse(result);
-        const native = parsed?.nativeToolSearch;
-        if (!native || typeof native !== 'object') return null;
-        const toolReferences = Array.isArray(native.toolReferences)
-            ? native.toolReferences.map((name) => String(name || '').trim()).filter(Boolean)
-            : [];
-        const openaiTools = Array.isArray(native.openaiTools)
-            ? native.openaiTools.filter((tool) => tool && typeof tool === 'object')
-            : [];
-        if (!toolReferences.length && !openaiTools.length) return null;
-        return {
-            toolReferences,
-            openaiTools,
-            summary: typeof native.summary === 'string' && native.summary
-                ? native.summary
-                : `Loaded deferred tools: ${toolReferences.join(', ') || openaiTools.map((tool) => tool.name).filter(Boolean).join(', ')}`,
+    diagnostics.totalMs = Date.now() - startedAt;
+    if (result && typeof result === 'object') {
+        result.diagnostics = {
+            ...(result.diagnostics || {}),
+            pipeline: diagnostics,
         };
-    } catch {
-        return null;
-    }
-}
-function extractBashSessionId(result) {
-    if (typeof result !== 'string') return null;
-    const match = BASH_SESSION_HEADER_RE.exec(result);
-    return match ? match[1] : null;
-}
-
-export function buildAgentBashSessionArgs(args, sessionRef) {
-    if (!isAgentOwner(sessionRef)) return null;
-    // run_in_background is a detached one-shot job, incompatible with the
-    // persistent bash session. Fall through to the background-job path
-    // (executeBuiltinTool -> startBackgroundShellJob) so the worker gets a
-    // task_id that task control can resolve — otherwise the persistent
-    // session returns a [session: ...] header and task control reports "task not found".
-    if (args?.run_in_background === true) return null;
-    const routedArgs = { ...(args || {}) };
-    const explicitSessionId = typeof routedArgs.session_id === 'string' && routedArgs.session_id.trim()
-        ? routedArgs.session_id.trim()
-        : null;
-    const wantsPersistent = routedArgs.persistent === true || !!explicitSessionId;
-    if (!wantsPersistent) return null;
-    if (!explicitSessionId && sessionRef?.implicitBashSessionId) {
-        routedArgs.session_id = sessionRef.implicitBashSessionId;
-    } else if (explicitSessionId) {
-        routedArgs.session_id = explicitSessionId;
     }
-    delete routedArgs.persistent;
-    return routedArgs;
-}
-
-export function formatMissingToolApprovalUiDenial(toolName, askReason) {
-    const reason = String(askReason || 'approval requested by hook').trim();
-    const name = String(toolName || 'tool');
-    return `Error: tool "${name}" denied by hook: approval required but no approval UI is available${reason ? ` (${reason})` : ''}`;
+    compactDebugLog('recall-fasttrack pipeline', diagnostics);
+    return result;
 }
-
-/**
- * Resolve PreToolUse `{ action: 'ask' }` against an optional approval callback.
- * Returns `{ denial }` when the tool must not run; otherwise `{ approval }`.
- */
-export async function resolvePreToolAskApproval({
-    toolName,
-    args,
-    cwd,
-    sessionId,
-    toolCallId,
-    askReason,
-    toolApprovalHook,
-}) {
-    const name = String(toolName || 'tool');
-    const reason = String(askReason || 'approval requested by hook').trim();
-    if (typeof toolApprovalHook !== 'function') {
-        return { denial: formatMissingToolApprovalUiDenial(name, reason) };
-    }
-    let approval;
-    try {
-        approval = await toolApprovalHook({
-            name,
-            args,
-            cwd,
-            sessionId,
-            toolCallId: toolCallId || null,
-            reason,
-        });
-    } catch (error) {
-        const detail = error?.message || String(error || 'approval failed');
-        return { denial: `Error: tool "${name}" denied by hook: ${detail}` };
-    }
-    if (!approvalGranted(approval)) {
-        const detail = approvalReason(approval, reason || 'not approved');
-        return { denial: `Error: tool "${name}" denied by hook: ${detail}` };
-    }
-    return { approval };
-}
-
 function _scopedCacheOutcomeForCall(sessionRef, toolCallId, toolName, callerSessionId, executeOpts = {}) {
     if (executeOpts.scopedCacheOutcome) {
         if (sessionRef && toolCallId) {
@@ -1238,13 +417,19 @@ async function executeTool(name, args, cwd, callerSessionId, sessionRef, execute
     }
     if (name === 'apply_patch') {
         const patchArgs = typeof args === 'string' ? { patch: args } : args;
-        return executePatchTool(name, patchArgs, cwd, { sessionId: callerSessionId });
+        return executePatchTool(name, patchArgs, cwd, { sessionId: callerSessionId, toolCallId: executeOpts.toolCallId || null });
     }
     if (isBuiltinTool(name)) {
         // clientHostPid threaded for the same per-terminal job-scope reason as
         // the bash branch above (see resolveJobOwnerHostPid).
         return executeBuiltinTool(name, args, cwd, completionToolOpts);
     }
+    if (isExternalAdapterTool(name)) {
+        // Foreign-CLI tool names (StrReplace/Write/bash variants) adapt to a
+        // native execution inside executeBuiltinTool's default: case; on a
+        // shape mismatch it falls back to the redirect guidance message.
+        return executeBuiltinTool(name, args, cwd, completionToolOpts);
+    }
     return formatUnknownBuiltinToolMessage(name, args, 'tool');
     })();
     if (typeof afterToolHook === 'function') {
@@ -1257,7 +442,14 @@ async function executeTool(name, args, cwd, callerSessionId, sessionRef, execute
                 toolCallId: executeOpts.toolCallId || null,
                 result: __result,
             });
-            return resolveToolResultAfterHook(__result, hookResult);
+            // Envelope-aware hook override: a PostToolUse hook may override the
+            // model-VISIBLE tool output (the envelope's `result` / stub), but it
+            // must NEVER drop the `newMessages` channel. Split first, apply the
+            // override to `result` only, then re-wrap so newMessages survive.
+            const { result: __res, newMessages: __nm } = normalizeToolEnvelope(__result);
+            const __overridden = resolveToolResultAfterHook(__res, hookResult);
+            if (__nm.length) return makeToolEnvelope(__overridden, __nm);
+            return __overridden;
         } catch {
             // PostToolUse hooks are best-effort; never let one break the tool result.
         }
@@ -1275,13 +467,6 @@ async function executeTool(name, args, cwd, callerSessionId, sessionRef, execute
  *                wrapper can propagate a clean cancellation.
  *   - `onStageChange(stage)` / `onStreamDelta()` — forwarded to provider.send for heartbeats
  */
-// Source of truth: defaults/hidden-roles.json (loaded via _getHiddenRoles
-// above). Build the name Set eagerly at module load so HIDDEN_ROLE_NAMES
-// stays in sync with the declarative registry — no hardcoded duplicate.
-const HIDDEN_ROLE_NAMES = new Set(
-    (_getHiddenRoles().roles || []).map((r) => r && r.name).filter((n) => typeof n === 'string' && n.length > 0)
-);
-
 // Stop reasons that signal the turn was cut short mid-synthesis (token cap,
 // provider pause). Empty content + one of these reasons means the worker
 // was not done — re-prompt instead of accepting empty as final.
@@ -1291,22 +476,6 @@ const INCOMPLETE_STOP_REASONS = new Set([
     'pause_turn', 'max_tokens', 'length', 'MAX_TOKENS', 'OTHER',
 ]);
 
-export function approvalGranted(value) {
-    if (value === true) return true;
-    if (!value || typeof value !== 'object') return false;
-    if (value.approved === true || value.allow === true || value.allowed === true) return true;
-    const decision = String(value.decision || value.action || value.result || '').trim().toLowerCase();
-    return decision === 'approve' || decision === 'approved' || decision === 'allow' || decision === 'yes';
-}
-
-export function approvalReason(value, fallback = '') {
-    if (value && typeof value === 'object') {
-        const reason = String(value.reason || value.message || '').trim();
-        if (reason) return reason;
-    }
-    return fallback;
-}
-
 export async function agentLoop(provider, messages, model, tools, onToolCall, cwd, sendOpts) {
     let iterations = 0;
     let toolCallsTotal = 0;
@@ -1315,6 +484,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     let response;
     let contractNudges = 0;
     let contextOverflowRetryUsed = false;
+    // Set when the hard iteration-cap break below fires. Consumed at the final
+    // return to tag terminationReason='iteration_cap' so a worker that exhausts
+    // the loop without a final answer surfaces to Lead as an explicit error
+    // instead of a silent empty "completed".
+    let terminatedByCap = false;
     // Set when a provider context-overflow refusal triggers the in-turn
     // reactive compact retry below; consumed by the next pre-send compact pass
     // so its telemetry/events carry trigger:'reactive' (distinct from the
@@ -1323,7 +497,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     const opts = sendOpts || {};
     const sessionId = opts.sessionId || null;
     const signal = opts.signal || null;
-    const sessionRole = opts.session?.role;
+    const sessionAgent = opts.session?.agent;
     const forcedFirstTool = opts.forcedFirstTool ?? null;
     const forcedFirstToolDef = forcedFirstTool
         ? tools.find(tool => tool?.name === forcedFirstTool)
@@ -1396,9 +570,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         });
         return true;
     };
-    const maxLoopIterations = Number.isFinite(sessionRef?.maxLoopIterations)
-        ? sessionRef.maxLoopIterations
-        : MAX_LOOP_ITERATIONS;
+    const maxLoopIterations = resolveSessionMaxLoopIterations(sessionRef);
     // Tool execution must use the session cwd even when the caller omitted the
     // legacy positional cwd argument. Agent workers always carry their cwd on
     // sessionRef; falling through to pwd()/process.cwd() resolves relatives
@@ -1408,6 +580,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         throwIfAborted();
         if (iterations >= maxLoopIterations) {
             process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
+            terminatedByCap = true;
             break;
         }
         // Drain queued steering/prompts BEFORE the
@@ -1460,6 +633,18 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 // them apart, then clear the one-shot flag.
                 const compactTrigger = reactiveOverflowRetryPending ? 'reactive' : 'auto';
                 reactiveOverflowRetryPending = false;
+                // PreCompact: bridge to the standard hook bus before compaction
+                // runs. session-property hook (manager/loop have no bus access).
+                // { trigger } normalized to 'auto'|'manual'. Best-effort.
+                {
+                    const _preCompactHook = typeof opts.preCompactHook === 'function'
+                        ? opts.preCompactHook
+                        : sessionRef?.preCompactHook;
+                    if (typeof _preCompactHook === 'function') {
+                        try { await _preCompactHook({ sessionId, cwd, trigger: compactTrigger === 'manual' ? 'manual' : 'auto' }); }
+                        catch { /* best-effort: PreCompact hook must never break compaction */ }
+                    }
+                }
                 rememberCompactTelemetry(sessionRef, compactPolicy, {
                     stage: 'compacting',
                     beforeTokens: messageTokensEst,
@@ -1570,6 +755,51 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     }
                     summaryChanged = messagesArrayChanged(compactInputMessages, compacted);
                 } catch (compactErr) {
+                    // Anchor-independent prune safety net. When SEMANTIC compact
+                    // throws (e.g. a degenerate single-turn transcript, or a
+                    // summary that cannot fit), attempt one non-LLM prune that
+                    // needs no user anchor: middle-truncate the oldest oversized
+                    // tool_result bodies until the transcript fits the budget.
+                    // If it shrinks the transcript we continue with that result
+                    // instead of escalating to overflow. Structure/pairing is
+                    // preserved (only string content shrinks) and the result is
+                    // re-reconciled inside the helper.
+                    //
+                    // GATED to the non-recall path: a recall-fasttrack failure
+                    // must NOT be silently recovered by this prune (that would
+                    // change the type-2 path's contract by shipping a pruned
+                    // transcript with no recall output). When recallFastTrackError
+                    // is set the fallback is skipped and the original overflow
+                    // escalation runs unchanged.
+                    if (!recallFastTrackError) {
+                        try {
+                            // Accept only if the pruned transcript fits the SAME
+                            // effective budget the prune targets (compactBudgetTokens
+                            // minus the request reserve) — comparing against the raw
+                            // compactBudgetTokens would accept a result with no
+                            // reserve headroom and overflow on the very next send.
+                            const acceptThreshold = compactEffectiveBudget(compactBudgetTokens, {
+                                reserveTokens: compactPolicy.reserveTokens,
+                            });
+                            const salvaged = pruneToolOutputsUnanchored(messages, compactBudgetTokens, {
+                                reserveTokens: compactPolicy.reserveTokens,
+                            });
+                            if (messagesArrayChanged(messages, salvaged)
+                                && estimateMessagesTokensSafe(salvaged) <= acceptThreshold) {
+                                compacted = salvaged;
+                                pruneCount = countPrunedToolOutputs(messages, salvaged);
+                                summaryChanged = true;
+                            }
+                        } catch { /* fall through to overflow escalation */ }
+                    }
+                    if (compacted !== undefined) {
+                        try {
+                            process.stderr.write(
+                                `[loop] compact fallback prune recovered (sess=${sessionId || 'unknown'}): ` +
+                                `${compactErr?.message || compactErr}\n`,
+                            );
+                        } catch { /* best-effort */ }
+                    } else {
                     const compactFailMsg = compactErr && compactErr.message ? compactErr.message : String(compactErr);
                     const semanticFailMsg = semanticCompactError?.message || null;
                     const recallFailMsg = recallFastTrackError?.message || null;
@@ -1593,6 +823,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                         iteration: iterations + 1,
                         stage: 'pre_send',
                         trigger: compactTrigger,
+                        compact_type: compactPolicy.compactType || compactPolicy.type || DEFAULT_COMPACT_TYPE,
                         prune_count: pruneCount,
                         compact_changed: false,
                         input_prefix_hash: messagePrefixHash(messages),
@@ -1602,13 +833,23 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                         after_bytes: getBeforeBytes(),
                         context_window: compactPolicy.contextWindow,
                         budget_tokens: compactPolicy.boundaryTokens,
+                        boundary_tokens: compactPolicy.boundaryTokens,
                         target_budget_tokens: compactBudgetTokens,
                         reserve_tokens: compactPolicy.reserveTokens,
+                        pressure_tokens: pressureTokens,
+                        trigger_tokens: compactPolicy.triggerTokens,
                         message_tokens_est: messageTokensEst,
+                        duration_ms: Date.now() - compactStartedAt,
                         provider: sessionRef.provider,
                         model: sessionRef.model || model,
                         error: compactFailMsg,
                         error_code: compactFailCode,
+                        details: {
+                            semantic: semanticCompactResult?.diagnostics || null,
+                            recallFastTrack: recallFastTrackResult?.diagnostics || null,
+                            semanticError: semanticFailMsg,
+                            recallFastTrackError: recallFailMsg,
+                        },
                     });
                     emitCompactEvent(opts, {
                         sessionId,
@@ -1640,6 +881,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                         reserveTokens: compactPolicy.reserveTokens,
                         messageTokensEst,
                     }, compactErr);
+                    }
                 }
                 try { opts.onStageChange?.('requesting'); } catch { /* best-effort */ }
                 const compactChanged = messagesArrayChanged(messages, compacted);
@@ -1684,6 +926,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     iteration: iterations + 1,
                     stage: 'pre_send',
                     trigger: compactTrigger,
+                    compact_type: compactPolicy.compactType || compactPolicy.type || DEFAULT_COMPACT_TYPE,
                     prune_count: pruneCount,
                     compact_changed: compactChanged || summaryChanged,
                     input_prefix_hash: messagePrefixHash(messages),
@@ -1693,11 +936,19 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     after_bytes: afterBytes,
                     context_window: compactPolicy.contextWindow,
                     budget_tokens: compactPolicy.boundaryTokens,
+                    boundary_tokens: compactPolicy.boundaryTokens,
                     target_budget_tokens: compactBudgetTokens,
                     reserve_tokens: compactPolicy.reserveTokens,
+                    pressure_tokens: pressureTokens,
+                    trigger_tokens: compactPolicy.triggerTokens,
                     message_tokens_est: messageTokensEst,
+                    duration_ms: compactDurationMs,
                     provider: sessionRef.provider,
                     model: sessionRef.model || model,
+                    details: {
+                        semantic: semanticCompactResult?.diagnostics || null,
+                        recallFastTrack: recallFastTrackResult?.diagnostics || null,
+                    },
                 });
                 emitCompactEvent(opts, {
                     sessionId,
@@ -1721,6 +972,17 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     durationMs: compactDurationMs,
                 });
             }
+            // PostCompact: bridge to the standard hook bus after compaction
+            // completes. session-property hook; { trigger } 'auto'|'manual'.
+            {
+                const _postCompactHook = typeof opts.postCompactHook === 'function'
+                    ? opts.postCompactHook
+                    : sessionRef?.postCompactHook;
+                if (typeof _postCompactHook === 'function') {
+                    try { await _postCompactHook({ sessionId, cwd, trigger: compactTrigger === 'manual' ? 'manual' : 'auto' }); }
+                    catch { /* best-effort: PostCompact hook must never break the loop */ }
+                }
+            }
         }
         const nextIteration = iterations + 1;
         opts.iteration = nextIteration;
@@ -1775,12 +1037,12 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             // Shared pre-dispatch deny: identical predicate runs in the
             // serial path below. If any role/permission guard would reject
             // this call there, never start it eagerly here.
-            if (_preDispatchDeny(call, toolKind, sessionRef) !== null) return null;
+            if (preDispatchDenyForSession(sessionRef, call, toolKind) !== null) return null;
             const entry = { startedAt: Date.now(), endedAt: null, mutationEpoch: _mutationEpoch };
             _eagerInFlightSigs.set(_sig, call.id);
             entry.promise = (async () => {
                 try {
-                    return { ok: true, value: await executeTool(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id, signal, notifyFn: opts.notifyFn, toolApprovalHook: opts.onToolApproval }) };
+                    return { ok: true, value: await executeTool(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id, signal, notifyFn: opts.notifyFn, toolApprovalHook: opts.onToolApproval, iteration: nextIteration }) };
                 } catch (error) {
                     return { ok: false, error };
                 }
@@ -1810,10 +1072,17 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     // calls (they return null above), so those `continue`-before-
                     // execution stub paths can never early-notify (contract #5).
                     try {
+                        // UI-only: surface the model-VISIBLE result (envelope
+                        // stub for envelope returns), never the envelope object
+                        // or its injected newMessages body — no [object Object],
+                        // no full skill body in the tool card.
+                        const _earlyVisible = settled && settled.ok
+                            ? normalizeToolEnvelope(settled.value).result
+                            : null;
                         const _earlyContent = settled && settled.ok
-                            ? (typeof settled.value === 'string'
-                                ? settled.value
-                                : (settled.value == null ? '' : String(settled.value)))
+                            ? (typeof _earlyVisible === 'string'
+                                ? _earlyVisible
+                                : (_earlyVisible == null ? '' : String(_earlyVisible)))
                             : `Error: ${settled && settled.error instanceof Error ? settled.error.message : String(settled && settled.error)}`;
                         opts.onToolResult?.({
                             role: 'tool',
@@ -1870,6 +1139,88 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         try {
             response = await provider.send(messages, model, sendTools.length ? sendTools : undefined, opts);
         } catch (sendErr) {
+            // Partial-final recovery (owner-notify fix): the recurring "worker
+            // finished but the task hung / no result delivered" case is a FINAL,
+            // no-tool summary stream that wedges (ping-only) AFTER all real tool
+            // work completed in earlier iterations. The provider attaches its
+            // partial stream state to the StreamStalledError. When the stall
+            // carries streamed assistant text, has NO pending tool_use, and did
+            // NOT emit a tool call this iteration, accept the partial as a
+            // successful terminal response (deliver the summary we have) instead
+            // of throwing — which would strand/notify-as-failure a turn whose
+            // work actually succeeded. A stall WITH a pending/emitted tool call
+            // is NOT recoverable (a tool whose input never completed must never
+            // look done) and falls through to the normal error path.
+            if (
+                sendErr?.streamStalled === true
+                && sendErr.pendingToolUse !== true
+                && sendErr.unsafeToRetry !== true
+                && typeof sendErr.partialContent === 'string'
+                && sendErr.partialContent.trim().length > 0
+                && !(Array.isArray(sendErr.partialToolCalls) && sendErr.partialToolCalls.length > 0)
+            ) {
+                try {
+                    process.stderr.write(
+                        `[loop] final stream stalled with partial text (sess=${sessionId || 'unknown'} `
+                        + `iter=${nextIteration} len=${sendErr.partialContent.length}); `
+                        + `accepting as partial-final success\n`,
+                    );
+                } catch { /* best-effort */ }
+                response = {
+                    content: sendErr.partialContent,
+                    model: sendErr.partialModel || model,
+                    toolCalls: undefined,
+                    usage: sendErr.partialUsage || undefined,
+                    stopReason: sendErr.partialStopReason || 'end_turn',
+                    hasThinkingContent: sendErr.partialHasThinking === true,
+                    partialFinal: true,
+                };
+            } else
+            // Partial tool-call recovery (agent-hang fix): a stream that stalls
+            // AFTER fully-parsed tool calls were emitted used to lose the whole
+            // turn — unsafeToRetry blocks the mid-stream replay (correct: a
+            // replay would re-run side-effecting tools) and the old code threw,
+            // discarding tool work that had ALREADY completed via eager dispatch.
+            // But the parsed calls are complete (pendingToolUse false ⇒ no
+            // half-streamed tool input), so instead of replaying the request we
+            // accept the partial as a normal tool-call turn and fall through to
+            // the standard execution path: eager-dispatched (read-only) calls
+            // resolve from the pending map without re-running, side-effecting
+            // calls were never started during streaming and execute exactly
+            // once. providerState stays undefined so the next iteration resends
+            // a full frame on a fresh stream.
+            if (
+                sendErr?.streamStalled === true
+                && sendErr.pendingToolUse !== true
+                && Array.isArray(sendErr.partialToolCalls)
+                && sendErr.partialToolCalls.length > 0
+            ) {
+                try {
+                    process.stderr.write(
+                        `[loop] stream stalled after ${sendErr.partialToolCalls.length} complete tool call(s) `
+                        + `(sess=${sessionId || 'unknown'} iter=${nextIteration}); `
+                        + `recovering as tool-call turn instead of failing\n`,
+                    );
+                } catch { /* best-effort */ }
+                try {
+                    appendAgentTrace({
+                        kind: 'stall_tool_recovery',
+                        sessionId: sessionId || null,
+                        iteration: nextIteration,
+                        toolCalls: sendErr.partialToolCalls.length,
+                        partialContentLen: typeof sendErr.partialContent === 'string' ? sendErr.partialContent.length : 0,
+                    });
+                } catch { /* best-effort */ }
+                response = {
+                    content: typeof sendErr.partialContent === 'string' ? sendErr.partialContent : '',
+                    model: sendErr.partialModel || model,
+                    toolCalls: sendErr.partialToolCalls.slice(),
+                    usage: sendErr.partialUsage || undefined,
+                    stopReason: 'tool_use',
+                    hasThinkingContent: sendErr.partialHasThinking === true,
+                    partialToolRecovery: true,
+                };
+            } else
             // Context-window-exceeded is a deterministic refusal from the API.
             // Recover context overflow reactively by compacting and retrying
             // in the same active turn. MixDog's proactive estimator can miss a
@@ -1922,13 +1273,18 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         // the stateless contract for providers that don't use continuation).
         providerState = response?.providerState ?? undefined;
         iterations = nextIteration;
-        traceAgentLoop({
-            sessionId,
-            iteration: iterations,
-            sendMs: Date.now() - sendStartedAt,
-            messageCount: Array.isArray(messages) ? messages.length : 0,
-            bodyBytesEst: estimateProviderPayloadBytes(messages, model, sendTools),
-        });
+        // Payload byte estimate serializes the FULL messages+tools array —
+        // only pay that cost when verbose loop tracing is actually enabled
+        // (traceAgentLoop is a no-op otherwise).
+        if (process.env.MIXDOG_AGENT_TRACE_VERBOSE === '1') {
+            traceAgentLoop({
+                sessionId,
+                iteration: iterations,
+                sendMs: Date.now() - sendStartedAt,
+                messageCount: Array.isArray(messages) ? messages.length : 0,
+                bodyBytesEst: estimateProviderPayloadBytes(messages, model, sendTools),
+            });
+        }
         // Accumulate usage across iterations — every billable slot, not just
         // input/output. Anthropic cache_read/cache_write typically stay 0 on
         // the first iteration and surge on later ones (warm prefix reuse),
@@ -1948,6 +1304,37 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         // Provider may have returned despite an abort (SDKs that don't honour
         // signal) — bail before processing any of its output.
         throwIfAborted();
+        // P1 audit fix (Step4): a text-only turn truncated by the provider's
+        // max-output limit (response.truncated, set by the provider layer
+        // when stopReason==='length' AND content is non-empty) used to look
+        // identical to a clean completion — the model's answer could be
+        // silently cut mid-sentence with zero signal to the operator. Surface
+        // it as a one-line stderr warning + trace event WITHOUT failing the
+        // turn (the partial content is still usable and the loop's own
+        // isIncompleteStop nudge below already re-prompts when content is
+        // empty).
+        if (response?.truncated === true) {
+            try {
+                process.stderr.write(
+                    `[loop] provider output truncated at max-output limit (sess=${sessionId || 'unknown'} `
+                    + `iter=${iterations} stopReason=${response.stopReason ?? response.stop_reason ?? 'length'} `
+                    + `contentLen=${typeof response.content === 'string' ? response.content.length : 0}); `
+                    + `answer may be cut off mid-sentence.\n`,
+                );
+            } catch { /* best-effort */ }
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'output_truncated',
+                    payload: {
+                        stop_reason: response.stopReason ?? response.stop_reason ?? 'length',
+                        content_len: typeof response.content === 'string' ? response.content.length : 0,
+                        agent: sessionAgent || null,
+                    },
+                });
+            } catch { /* best-effort */ }
+        }
         // Incremental metric persistence (fix A): push per-iteration token delta
         // immediately so watchdog / agent type=list sees live totals mid-turn.
         if (sessionId && opts.onUsageDelta && response.usage) {
@@ -1994,7 +1381,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             //     reminders waste turns and fragment the working context, so
             //     the second empty turn is accepted as terminal.
             const hasContent = typeof response.content === 'string' && response.content.trim().length > 0;
-            const isHidden = HIDDEN_ROLE_NAMES.has(sessionRole);
+            const isHidden = HIDDEN_AGENT_NAMES.has(sessionAgent);
             const stopReason = response.stopReason ?? response.stop_reason ?? null;
             const isIncompleteStop = stopReason && INCOMPLETE_STOP_REASONS.has(stopReason);
             // A user/schedule notification can arrive while provider.send() is
@@ -2091,6 +1478,14 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         }
         // R15: per-turn scalar read-count Map. Lifetime = this turn's tool-call batch.
         // Declared between the duplicate-detection block and the for-loop so it resets
+        // Per-batch buffer for the general `newMessages` tool-result channel.
+        // A tool MAY return a `{ __toolEnvelope, result, newMessages }` envelope;
+        // its newMessages (e.g. the Skill SKILL.md body as a role:'user' message)
+        // are collected here across EVERY call in this assistant turn and flushed
+        // ONCE, AFTER the batch's last tool_result is pushed — never interleaved
+        // between two tool results of the same multi-tool turn (which would put a
+        // user message between tool(A) and tool(B) and break provider pairing).
+        const _batchNewMessages = [];
         for (let callIndex = 0; callIndex < calls.length; callIndex += 1) {
             const call = calls[callIndex];
             if (isBuiltinTool(call.name)) {
@@ -2131,8 +1526,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             let toolStartedAt;
             let toolEndedAt;
             const toolKind = getToolKind(call.name);
-            // Cross-turn read dedup. Mirrors a reference agent's
-            // fileReadCache.ts: if the path's stat tuple (mtime/size/ino/dev)
+            // Cross-turn read dedup: if the path's stat tuple (mtime/size/ino/dev)
             // is unchanged since a prior read in THIS session, return the cached
             // body instead of executing. Both scalar and array/object-array path
             // forms are cached — keyed by (abs, offset, limit, mode, n) per entry.
@@ -2216,18 +1610,18 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     // Runtime pre-dispatch deny. Schema profiles may hide
                     // tools for routing efficiency, but this remains the
                     // control-plane boundary for any tool_use that still
-                    // reaches the loop. _preDispatchDeny is the SHARED helper
+                    // reaches the loop. preDispatchDenyForSession is the SHARED helper
                     // used by both the eager dispatch path (startEagerTool)
                     // and this serial path — keeps the agent-owned control-
                     // plane reject and no-tool role guards consistent across
                     // both paths.
-                    const _denyMsg = _preDispatchDeny(call, toolKind, sessionRef);
+                    const _denyMsg = preDispatchDenyForSession(sessionRef, call, toolKind);
                     if (_denyMsg !== null) {
                         result = _denyMsg;
                         toolEndedAt = Date.now();
                         _resultKind = 'error';
                     } else {
-                        result = await executeTool(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id, signal, notifyFn: opts.notifyFn, toolApprovalHook: opts.onToolApproval });
+                        result = await executeTool(call.name, call.arguments, cwd, sessionId, sessionRef, { toolCallId: call.id, signal, notifyFn: opts.notifyFn, toolApprovalHook: opts.onToolApproval, iteration: iterations });
                         toolEndedAt = Date.now();
                         // Boundary: tool-return string convention → structural kind.
                         // The only prefix check in this codebase; downstream layers
@@ -2249,6 +1643,48 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 result = `Error: ${err instanceof Error ? err.message : String(err)}`;
                 _resultKind = 'error';
             }
+            // CENTRAL ENVELOPE NORMALIZE (general newMessages channel).
+            // executeTool (serial + eager) and cache/error paths above all
+            // funnel into `result`. Split ONCE here: downstream post-processing
+            // (classifyResultKind / maybeOffloadToolResult / compressToolResult /
+            // traceAgentTool / cache writes / messages.push) sees ONLY the
+            // model-visible `result`; the `newMessages` ride a per-batch buffer
+            // flushed after the batch's last tool_result (never interleaved).
+            {
+                const _env = normalizeToolEnvelope(result);
+                result = _env.result;
+                if (_env.newMessages.length) _batchNewMessages.push(..._env.newMessages);
+            }
+            // Bounded-map cleanup: a scoped-cache outcome recorded for this call.id
+            // (via _scopedCacheOutcomeForCall) is only ever consumed/deleted on the
+            // success path below (_executeOk && _resultKind==='normal'). A failed or
+            // errored call would otherwise leak its entry in
+            // sessionRef._scopedCacheOutcomeByCallId forever — reclaim it here.
+            if (sessionRef?._scopedCacheOutcomeByCallId && call?.id && (!_executeOk || _resultKind === 'error')) {
+                sessionRef._scopedCacheOutcomeByCallId.delete(call.id);
+            }
+            // PostToolUseFailure: a tool that resolved to a failure (thrown-error
+            // path -> `Error:` string, or an is_error result classified as
+            // 'error') fires the optional session failure hook. Same shape as
+            // afterToolHook; `result` carries the error text. Best-effort — a
+            // hook error must never wedge the tool loop.
+            if (!_executeOk || _resultKind === 'error') {
+                const _afterToolFailureHook = typeof opts.afterToolFailureHook === 'function'
+                    ? opts.afterToolFailureHook
+                    : sessionRef?.afterToolFailureHook;
+                if (typeof _afterToolFailureHook === 'function') {
+                    try {
+                        await _afterToolFailureHook({
+                            name: call.name,
+                            args: call.arguments,
+                            cwd,
+                            sessionId,
+                            toolCallId: call.id,
+                            result: typeof result === 'string' ? result : String(result ?? ''),
+                        });
+                    } catch { /* best-effort: PostToolUseFailure hook must never break the loop */ }
+                }
+            }
             // Update the cross-iteration repeat-failure guard with this call's
             // outcome: bump the consecutive-failure count for an identical
             // signature, or clear it the moment the same call succeeds.
@@ -2400,7 +1836,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     toolKind,
                     toolMs: toolEndedAt - toolStartedAt,
                     toolArgs: call.arguments,
-                    role: sessionRef?.role || null,
+                    agent: sessionRef?.agent || null,
                     model: sessionRef?.model || null,
                     resultKind: _resultKind,
                     resultText: result,
@@ -2432,12 +1868,22 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                         setReadCached({ sessionId, args: call.arguments, cwd, content: result, toolUseId: call.id });
                     }
                 }
+                // UI-only: apply_patch stashes the standard unified diff keyed
+                // by tool_use id (never in the model-visible result). Attach it
+                // here as a side-channel field so the TUI's expanded (ctrl+o)
+                // raw view renders a colored +/- diff. The provider lowering
+                // (anthropic/openai/etc.) never reads `uiDiff`, so the model
+                // sees only `content` (the compact summary) — no token bloat.
+                const _applyPatchUiDiff = _stripMcpPrefix(call.name) === 'apply_patch'
+                    ? takeApplyPatchUiDiff(call.id)
+                    : null;
                 pushToolResultMessage({
                     role: 'tool',
                     content: result,
                     toolCallId: call.id,
                     toolKind: _resultKind,
                     ...(_nativeToolSearch ? { nativeToolSearch: _nativeToolSearch } : {}),
+                    ...(_applyPatchUiDiff ? { uiDiff: _applyPatchUiDiff } : {}),
                 });
             } catch (postErr) {
                 _postProcessOk = false;
@@ -2453,7 +1899,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     toolKind,
                     toolMs: toolEndedAt && toolStartedAt ? toolEndedAt - toolStartedAt : null,
                     toolArgs: call.arguments,
-                    role: sessionRef?.role || null,
+                    agent: sessionRef?.agent || null,
                     model: sessionRef?.model || null,
                     cwd,
                     resultText: _postMsg,
@@ -2477,6 +1923,44 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             // discard the rest of the batch and skip the next provider.send.
             throwIfAborted();
         }
+        // Flush the per-batch newMessages channel. All tool_results for this
+        // assistant turn are now pushed; appending the injected role:'user'
+        // messages here (AFTER the last tool_result, BEFORE the next provider
+        // send) keeps provider pairing valid — no user message is interleaved
+        // between tool(A) and tool(B). pre-send repairTranscriptBeforeProviderSend
+        // normalizes any residual ordering. The injected messages carry their
+        // own meta flag (e.g. meta:'skill') so compaction's latest-human-prompt
+        // selection does not mistake them for the user's request.
+        for (const _nm of _batchNewMessages) {
+            if (!_nm || _nm.role !== 'user' || typeof _nm.content !== 'string' || !_nm.content) continue;
+            messages.push({ role: 'user', content: _nm.content, ...(_nm.meta ? { meta: _nm.meta } : {}) });
+        }
+        // PostToolBatch: the full parallel batch of tool calls for this
+        // assistant turn has resolved and all tool_results are pushed. Fire the
+        // optional session hook before the next model call. No matcher event.
+        // Block support: if the hook returns blocked===true, inject its reason
+        // as a system-note user message for the next send (natural mechanism —
+        // same channel the newMessages flush just used). Best-effort otherwise.
+        {
+            const _afterToolBatchHook = typeof opts.afterToolBatchHook === 'function'
+                ? opts.afterToolBatchHook
+                : sessionRef?.afterToolBatchHook;
+            if (typeof _afterToolBatchHook === 'function' && calls.length > 0) {
+                try {
+                    const _batchDecision = await _afterToolBatchHook({
+                        sessionId,
+                        cwd,
+                        toolCount: calls.length,
+                    });
+                    if (_batchDecision?.blocked === true) {
+                        const _reason = String(_batchDecision.reason || 'PostToolBatch hook blocked continuation').trim();
+                        if (_reason) {
+                            messages.push({ role: 'user', content: `<system-reminder>\n${_reason}\n</system-reminder>`, meta: 'hook' });
+                        }
+                    }
+                } catch { /* best-effort: PostToolBatch hook must never break the loop */ }
+            }
+        }
         // Mid-turn steering is drained at the next loop's pre-send point,
         // AFTER any auto-compact pass. Draining here would put the steering
         // user turn after the fresh tool results before compaction runs; then
@@ -2485,6 +1969,33 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         // About to re-send with tool results — transition back to connecting for the next turn.
         if (sessionId) updateSessionStage(sessionId, 'connecting');
     }
+    // Classify WHY the loop ended so agent-tool can promote an empty/abnormal
+    // finish to an explicit Lead-facing error instead of a silent empty
+    // "completed". Determine "has content" exactly the way the no-tool-call
+    // branch above does (trimmed string content, or any reasoning content).
+    const _finalHasContent = (typeof response?.content === 'string' && response.content.trim().length > 0)
+        || (typeof response?.reasoningContent === 'string' && response.reasoningContent.trim().length > 0);
+    const _finalStopReason = response?.stopReason ?? response?.stop_reason ?? null;
+    const _finalIncompleteStop = _finalStopReason && INCOMPLETE_STOP_REASONS.has(_finalStopReason);
+    const _finalIsHidden = HIDDEN_AGENT_NAMES.has(sessionAgent);
+    let terminationReason;
+    if (terminatedByCap) {
+        // Real problem regardless of hidden/public: the loop never terminated
+        // on its own contract.
+        terminationReason = 'iteration_cap';
+    } else if (!_finalHasContent && _finalIncompleteStop) {
+        // Cut short mid-synthesis (token cap / provider pause). Real problem
+        // for hidden agents too.
+        terminationReason = 'truncated';
+    } else if (!_finalHasContent && !_finalIsHidden) {
+        // Empty terminal turn. Only public agents violate their contract by
+        // finishing empty — hidden agents (explorer/cycle/…) legitimately emit
+        // text-only/empty terminal turns per their own role contract, so leave
+        // terminationReason undefined for them.
+        terminationReason = 'empty';
+    } else {
+        terminationReason = undefined;
+    }
     return {
         ...response,
         usage: lastUsage || response.usage,
@@ -2493,5 +2004,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         iterations,
         toolCallsTotal,
         providerState,
+        terminationReason,
+        maxLoopIterations,
     };
 }