mixdog 0.9.0 → 0.9.2

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

@@ -2,27 +2,34 @@ import { classifyResultKind } from './result-classification.mjs';
 import { executeMcpTool, isMcpTool, mcpToolHasField } from '../mcp/client.mjs';
 import { canonicalizeBuiltinToolName, executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool } 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 { collectSkillsCached, loadSkillResource, buildSkillToolEnvelope } from '../context/collect.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 {
+    estimateMessagesTokens,
+    estimateRequestReserveTokens,
+    sanitizeToolPairs,
+    resolveCompactBufferRatio,
+    resolveCompactBufferTokens,
+} from './context-utils.mjs';
 import {
     recallFastTrackCompactMessages,
     pruneToolOutputs,
+    pruneToolOutputsUnanchored,
     semanticCompactMessages,
+    effectiveBudget as compactEffectiveBudget,
     compactTypeIsRecallFastTrack,
     compactTypeIsSemantic,
     normalizeCompactType,
     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';
@@ -126,9 +133,9 @@ function _preDispatchDeny(call, toolKind, sessionRef) {
     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).`;
+    const noToolAgent = sessionRef?.agent === 'cycle1-agent' || sessionRef?.agent === 'cycle2-agent';
+    if (noToolAgent) {
+        return `Error: tool "${name}" is not available in agent "${sessionRef.agent}". Re-emit the answer as pipe-separated text per the agent's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
     }
     return null;
 }
@@ -151,6 +158,27 @@ function estimateMessagesTokensSafe(messages) {
     catch { return null; }
 }
 
+function compactDebugEnabled() {
+    return String(process.env.MIXDOG_COMPACT_DEBUG || '').trim() === '1';
+}
+
+function compactDiagnosticError(err) {
+    if (!err) return null;
+    const text = String(err?.message || err);
+    return text.length > 500 ? `${text.slice(0, 499)}…` : text;
+}
+
+function compactByteLength(text) {
+    try { return Buffer.byteLength(String(text || ''), 'utf8'); }
+    catch { return String(text || '').length; }
+}
+
+function compactDebugLog(scope, details = {}) {
+    if (!compactDebugEnabled()) return;
+    try { process.stderr.write(`[compact] ${scope} ${JSON.stringify(details)}\n`); }
+    catch { /* best-effort diagnostics only */ }
+}
+
 function steeringContentText(content) {
     if (typeof content === 'string') return content;
     if (Array.isArray(content)) {
@@ -255,21 +283,20 @@ function agentContextOverflowError({ stage, sessionId, sessionRef, model, budget
 // 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;
+const _AGENTS_JSON = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../defaults/agents.json');
+let _hiddenAgentsCache = null;
+function _getHiddenAgents() {
+    if (_hiddenAgentsCache) return _hiddenAgentsCache;
     try {
-        _hiddenRolesCache = JSON.parse(_readFileSync(_HIDDEN_ROLES_JSON, 'utf8'));
-    } catch { _hiddenRolesCache = { roles: [] }; }
-    return _hiddenRolesCache;
+        _hiddenAgentsCache = JSON.parse(_readFileSync(_AGENTS_JSON, 'utf8'));
+    } catch { _hiddenAgentsCache = { agents: [] }; }
+    return _hiddenAgentsCache;
 }
 // Transcript pairing guard. Anthropic 400-rejects when an assistant message
 // ends with tool_use blocks and the next message isn't tool results for
@@ -443,6 +470,27 @@ function resolveCompactTypeSetting(_sessionRef, cfg = {}) {
 
 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 +502,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 +513,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 +526,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 +556,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,97 +589,15 @@ 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;
+    diagnostics.totalMs = Date.now() - startedAt;
+    if (result && typeof result === 'object') {
+        result.diagnostics = {
+            ...(result.diagnostics || {}),
+            pipeline: diagnostics,
+        };
     }
-    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,
-    });
+    compactDebugLog('recall-fasttrack pipeline', diagnostics);
+    return result;
 }
 const COMPACT_TARGET_RATIO = 0.02;
 const COMPACT_TARGET_MIN_TOKENS = 4_000;
@@ -947,9 +938,12 @@ function buildSkillsListResponse(cwd) {
 }
 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>`;
+    const res = loadSkillResource(name, cwd);
+    if (!res) return `Error: skill "${name}" not found`;
+    // Return the general tool envelope: the model-visible tool_result is the
+    // short stub (`Loaded skill: <name>`) and the full SKILL.md body is
+    // delivered ONCE as a separate injected role:'user' message (newMessages).
+    return buildSkillToolEnvelope(name, res.content, res.dir);
 }
 
 /** Normalize PostToolUse hook override values (legacy MCP text envelopes only). */
@@ -1238,7 +1232,7 @@ 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
@@ -1257,7 +1251,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,11 +1276,11 @@ 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
+// Source of truth: defaults/agents.json (loaded via _getHiddenAgents
+// above). Build the name Set eagerly at module load so HIDDEN_AGENT_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)
+const HIDDEN_AGENT_NAMES = new Set(
+    (_getHiddenAgents().agents || []).map((r) => r && r.agent).filter((n) => typeof n === 'string' && n.length > 0)
 );
 
 // Stop reasons that signal the turn was cut short mid-synthesis (token cap,
@@ -1315,6 +1316,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 +1329,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 +1402,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 +1412,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
@@ -1570,6 +1575,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 +1643,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 +1653,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 +1701,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 +1746,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 +1756,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,
@@ -1780,7 +1851,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             _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 +1881,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 +1948,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
@@ -1948,6 +2108,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 +2185,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 +2282,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)) {
@@ -2227,7 +2426,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                         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 +2448,18 @@ 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);
+            }
             // 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 +2611,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 +2643,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 +2674,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 +2698,18 @@ 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 } : {}) });
+        }
         // 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 +2718,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 +2753,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         iterations,
         toolCallsTotal,
         providerState,
+        terminationReason,
+        maxLoopIterations,
     };
 }