mixdog 0.9.3 → 0.9.5

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

@@ -1,31 +1,23 @@
 import { classifyResultKind } from './result-classification.mjs';
-import { executeMcpTool, isMcpTool, mcpToolHasField } from '../mcp/client.mjs';
-import { canonicalizeBuiltinToolName, executeBuiltinTool, formatUnknownBuiltinToolMessage, isBuiltinTool, isExternalAdapterTool } from '../tools/builtin.mjs';
-import { executeBashSessionTool } from '../tools/bash-session.mjs';
-import { executePatchTool, takeApplyPatchUiDiff } from '../tools/patch.mjs';
+import { canonicalizeBuiltinToolName, executeBuiltinTool, isBuiltinTool } from '../tools/builtin.mjs';
+import { takeApplyPatchUiDiff } from '../tools/patch.mjs';
 import { executeInternalTool, isInternalTool } from '../internal-tools.mjs';
-import { normalizeToolEnvelope, makeToolEnvelope } from './tool-envelope.mjs';
+import { normalizeToolEnvelope } 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 { resolveSessionMaxLoopIterations, WORKER_SOFT_CAP_ITERATIONS, isWorkerSoftCapSession } from '../agent-runtime/agent-loop-policy.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
-import { markSessionToolCall, updateSessionStage, SessionClosedError, getSessionAbortSignal, enqueuePendingMessage, bumpUsageMetricsEpoch } from './manager.mjs';
+import { markSessionToolCall, updateSessionStage, SessionClosedError, bumpUsageMetricsEpoch } from './manager.mjs';
 import {
-    recallFastTrackCompactMessages,
     pruneToolOutputs,
     pruneToolOutputsUnanchored,
     semanticCompactMessages,
     effectiveBudget as compactEffectiveBudget,
     DEFAULT_COMPACT_TYPE,
-    drainSessionCycle1,
-    countRawPendingRows,
 } from './compact.mjs';
 import { isContextOverflowError } from '../providers/retry-classifier.mjs';
 import { stripSoftWarns } from '../tool-loop-guard.mjs';
 import { maybeOffloadToolResult } from './tool-result-offload.mjs';
 import { tryReadCached, setReadCached, invalidatePathForSession, markPostEdit, consumePostEditMark, clearReadDedupSession, extractTouchedPathsFromPatch, tryScopedToolCached, setScopedToolCached, clearScopedToolsForSession, clearScopedToolsForSessionPaths, invalidatePrefetchCache } from './read-dedup.mjs';
-import { createScopedCacheOutcome } from './cache/scoped-cache-outcome.mjs';
-import { modelVisibleToolCompletionMessage } from '../../../shared/tool-execution-contract.mjs';
-import { createHash } from 'crypto';
 import { isInvalidToolArgsMarker, formatInvalidToolArgsResult } from '../providers/openai-compat-stream.mjs';
 
 import {
@@ -37,13 +29,8 @@ import {
     _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');
-    const mod = await codeGraphRuntimePromise;
-    if (typeof mod.executeCodeGraphTool !== 'function') throw new Error('code_graph runtime is not available');
-    return mod.executeCodeGraphTool(name, args, cwd, signal, options);
-}
+import { runRecallFastTrackCompact } from './loop/recall-fasttrack.mjs';
+import { executeTool, _scopedCacheOutcomeForCall } from './loop/tool-exec.mjs';
 
 // classifyResultKind is imported from result-classification.mjs at the top of
 // this file; import it from there directly rather than via this module.
@@ -58,6 +45,13 @@ import {
     compactDebugLog,
 } from './loop/compact-debug.mjs';
 import { mergeSteeringEntries, steeringContentText } from './loop/steering.mjs';
+import {
+    crossTurnSignature,
+    crossTurnDedupStub,
+    SOFT_CAP_WRAPUP_MESSAGE,
+    SOFT_CAP_REFUSAL_STUB,
+} from './loop/completion-guards.mjs';
+import { isEditProgressTool } from './loop/completion-guards.mjs';
 import { agentContextOverflowError } from './loop/context-overflow.mjs';
 import { positiveTokenInt } from './loop/env.mjs';
 import { normalizeUsage, addUsage } from './loop/usage.mjs';
@@ -76,12 +70,9 @@ import {
     isEagerDispatchable,
     messagesArrayChanged,
     getToolKind,
-    buildSkillsListResponse,
-    viewSkill,
     normalizeHookUpdatedToolOutput,
     resolveToolResultAfterHook,
     parseNativeToolSearchPayload,
-    extractBashSessionId,
     buildAgentBashSessionArgs,
     formatMissingToolApprovalUiDenial,
     resolvePreToolAskApproval,
@@ -93,6 +84,8 @@ import {
     restoreToolCallBodyForId,
 } from './loop/stored-tool-args.mjs';
 import { repairTranscriptBeforeProviderSend } from './loop/transcript-repair.mjs';
+import { classifyTerminationReason, INCOMPLETE_STOP_REASONS } from './loop/termination.mjs';
+import { createSteeringLadder } from './loop/steering-ladder.mjs';
 
 // 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
@@ -120,342 +113,8 @@ export {
 // 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;
-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 = {
-        callerSessionId: sessionId || null,
-        callerCwd: sessionRef?.cwd || undefined,
-        routingSessionId: sessionId || null,
-        clientHostPid: sessionRef?.clientHostPid,
-        signal: signal || null,
-    };
-    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',
-            sessionId,
-            messages,
-            cwd: sessionRef?.cwd,
-            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',
-        sessionId,
-        includeRaw: true,
-        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
-            // carrying the unprocessed transcript tail (single-pass left raw in).
-            const drained = await drainSessionCycle1(runTool, {
-                sessionId,
-                dumpArgs,
-                deadlineMs: positiveTokenInt(sessionRef?.compaction?.recallCycle1DeadlineMs) || 120_000,
-                maxPasses: positiveTokenInt(sessionRef?.compaction?.recallCycle1MaxPasses) || 0,
-                cycleArgs: {
-                    min_batch: 1,
-                    session_cap: 1,
-                    batch_size: positiveTokenInt(sessionRef?.compaction?.recallCycle1BatchSize) || 100,
-                    rows_per_session: positiveTokenInt(sessionRef?.compaction?.recallRowsPerSession) || 100,
-                    window_size: positiveTokenInt(sessionRef?.compaction?.recallWindowSize) || 20,
-                    concurrency: positiveTokenInt(sessionRef?.compaction?.recallConcurrency) || 5,
-                },
-            });
-            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)';
-    }
-    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: combinedRecallText,
-        query,
-        querySha,
-        allowEmptyRecall: true,
-        tailTurns: compactPolicy.tailTurns,
-        keepTokens: compactPolicy.keepTokens,
-        preserveRecentTokens: compactPolicy.preserveRecentTokens,
-    });
-    diagnostics.totalMs = Date.now() - startedAt;
-    if (result && typeof result === 'object') {
-        result.diagnostics = {
-            ...(result.diagnostics || {}),
-            pipeline: diagnostics,
-        };
-    }
-    compactDebugLog('recall-fasttrack pipeline', diagnostics);
-    return result;
-}
-function _scopedCacheOutcomeForCall(sessionRef, toolCallId, toolName, callerSessionId, executeOpts = {}) {
-    if (executeOpts.scopedCacheOutcome) {
-        if (sessionRef && toolCallId) {
-            if (!sessionRef._scopedCacheOutcomeByCallId) sessionRef._scopedCacheOutcomeByCallId = new Map();
-            sessionRef._scopedCacheOutcomeByCallId.set(toolCallId, executeOpts.scopedCacheOutcome);
-        }
-        return executeOpts.scopedCacheOutcome;
-    }
-    if (!callerSessionId || !toolCallId || !_isScopedCacheableTool(toolName)) return null;
-    const outcome = createScopedCacheOutcome();
-    if (sessionRef) {
-        if (!sessionRef._scopedCacheOutcomeByCallId) sessionRef._scopedCacheOutcomeByCallId = new Map();
-        sessionRef._scopedCacheOutcomeByCallId.set(toolCallId, outcome);
-    }
-    return outcome;
-}
-
-async function executeTool(name, args, cwd, callerSessionId, sessionRef, executeOpts = {}) {
-    const scopedCacheOutcome = _scopedCacheOutcomeForCall(
-        sessionRef,
-        executeOpts.toolCallId,
-        name,
-        callerSessionId,
-        executeOpts,
-    );
-    const toolOpts = scopedCacheOutcome
-        ? { ...executeOpts, scopedCacheOutcome }
-        : executeOpts;
-    const notificationSessionId = String(executeOpts.notifySessionId || sessionRef?.ownerSessionId || callerSessionId || '').trim();
-    const notifyFn = typeof executeOpts.notifyFn === 'function'
-        ? executeOpts.notifyFn
-        : (text, meta = {}) => {
-            if (!notificationSessionId) return;
-            try {
-                const visible = modelVisibleToolCompletionMessage(text, meta);
-                if (visible) enqueuePendingMessage(notificationSessionId, visible);
-            } catch { /* best effort */ }
-        };
-    const completionToolOpts = {
-        ...toolOpts,
-        sessionId: callerSessionId,
-        callerSessionId: notificationSessionId || callerSessionId,
-        routingSessionId: callerSessionId,
-        clientHostPid: sessionRef?.clientHostPid,
-        notifyFn,
-    };
-    const beforeToolHook = typeof executeOpts.beforeToolHook === 'function'
-        ? executeOpts.beforeToolHook
-        : sessionRef?.beforeToolHook;
-    const toolApprovalHook = typeof executeOpts.toolApprovalHook === 'function'
-        ? executeOpts.toolApprovalHook
-        : sessionRef?.toolApprovalHook;
-    if (beforeToolHook) {
-        try {
-            const decision = await beforeToolHook({
-                name,
-                args,
-                cwd,
-                sessionId: callerSessionId,
-                toolCallId: executeOpts.toolCallId || null,
-            });
-            const action = String(decision?.action || decision?.decision || '').toLowerCase();
-            if (action === 'deny' || action === 'block') {
-                const reason = decision?.reason ? `: ${decision.reason}` : '';
-                return `Error: tool "${name}" denied by hook${reason}`;
-            }
-            if (action === 'ask') {
-                const askReason = String(decision?.reason || 'approval requested by hook').trim();
-                const askOutcome = await resolvePreToolAskApproval({
-                    toolName: name,
-                    args,
-                    cwd,
-                    sessionId: callerSessionId,
-                    toolCallId: executeOpts.toolCallId || null,
-                    askReason,
-                    toolApprovalHook,
-                });
-                if (askOutcome.denial) return askOutcome.denial;
-                const approval = askOutcome.approval;
-                if (approval && typeof approval === 'object' && approval.args && typeof approval.args === 'object' && !Array.isArray(approval.args)) {
-                    args = approval.args;
-                }
-            }
-            if ((action === 'modify' || action === 'rewrite') && decision?.args && typeof decision.args === 'object' && !Array.isArray(decision.args)) {
-                args = decision.args;
-            }
-        } catch {
-            // Hooks are policy extensions. A broken hook must not wedge the agent loop.
-        }
-    }
-    const afterToolHook = typeof executeOpts.afterToolHook === 'function'
-        ? executeOpts.afterToolHook
-        : sessionRef?.afterToolHook;
-    const __result = await (async () => {
-    if (name === 'Skill') {
-        return viewSkill(cwd, args?.name);
-    }
-    if (name === 'skills_list') {
-        return buildSkillsListResponse(cwd);
-    }
-    if (name === 'skill_view') {
-        return viewSkill(cwd, args?.name);
-    }
-    if (isMcpTool(name)) {
-        // 24h trace data shows ~24% of external MCP calls are cwd-sensitive
-        // (bash / grep / read / list / glob etc.) but the worker session's
-        // cwd was previously dropped here. Inject cwd only when the tool's
-        // inputSchema declares the field — schemas without it would reject
-        // an unknown argument.
-        const needsCwdInjection = cwd
-            && mcpToolHasField(name, 'cwd')
-            && (args == null || args.cwd == null);
-        const finalArgs = needsCwdInjection ? { ...(args || {}), cwd } : args;
-        return executeMcpTool(name, finalArgs);
-    }
-    if (name === 'code_graph') {
-        // cwd chain: args.cwd (caller-explicit) → session cwd → undefined (handler throws)
-        const graphCwd = (typeof args?.cwd === 'string' && args.cwd.trim()) ? args.cwd.trim() : cwd;
-        return executeCodeGraphToolLazy(name, args, graphCwd, null, toolOpts);
-    }
-    if (isInternalTool(name)) {
-        // callerSessionId propagates into server.mjs dispatchTool so that
-        // dispatchAiWrapped can detect and reject recursive calls from a
-        // hidden-role session (recall/search/explore → self).
-        return executeInternalTool(name, args, {
-            callerSessionId,
-            callerCwd: cwd,
-            clientHostPid: sessionRef?.clientHostPid,
-            signal: executeOpts.signal,
-            routingSessionId: callerSessionId,
-            notifyFn,
-        });
-    }
-    if (name === 'shell') {
-        const routedArgs = buildAgentBashSessionArgs(args, sessionRef);
-        if (!routedArgs) {
-            // clientHostPid scopes background shell-jobs to the dispatching
-            // terminal's claude.exe pid (agent sessions store it on sessionRef);
-            // without it resolveJobOwnerHostPid falls back to the daemon-global env.
-            return executeBuiltinTool(name, args, cwd, completionToolOpts);
-        }
-        // Thread the session's AbortSignal so agent type=close can interrupt the
-        // persistent child process. getSessionAbortSignal is imported at top of
-        // loop.mjs from manager.mjs; callerSessionId identifies the controller.
-        let _bashAbortSignal = null;
-        try { _bashAbortSignal = getSessionAbortSignal(callerSessionId); } catch { /* ignore */ }
-        const result = await executeBashSessionTool('bash_session', routedArgs, cwd, {
-            sessionId: callerSessionId,
-            abortSignal: _bashAbortSignal,
-        });
-        const bashSid = extractBashSessionId(result);
-        if (bashSid) {
-            sessionRef.implicitBashSessionId = bashSid;
-            // Track all persistent bash sessions for bulk teardown on close.
-            if (sessionRef.allBashSessionIds) {
-                if (!sessionRef.allBashSessionIds.includes(bashSid)) {
-                    sessionRef.allBashSessionIds.push(bashSid);
-                }
-            } else {
-                sessionRef.allBashSessionIds = [bashSid];
-            }
-        }
-        return result;
-    }
-    if (name === 'apply_patch') {
-        const patchArgs = typeof args === 'string' ? { patch: args } : args;
-        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') {
-        try {
-            const hookResult = await afterToolHook({
-                name,
-                args,
-                cwd,
-                sessionId: callerSessionId,
-                toolCallId: executeOpts.toolCallId || null,
-                result: __result,
-            });
-            // 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.
-        }
-    }
-    return __result;
-}
+// _scopedCacheOutcomeForCall and executeTool moved to ./loop/tool-exec.mjs
+// (imported above).
 /**
  * Agent loop: send → tool_call → execute → re-send → repeat until text.
  * sendOpts may include:
@@ -472,10 +131,6 @@ async function executeTool(name, args, cwd, callerSessionId, sessionRef, execute
 // was not done — re-prompt instead of accepting empty as final.
 // Covers Anthropic (pause_turn, max_tokens), OpenAI (length), Gemini
 // (MAX_TOKENS, OTHER), and case variants.
-const INCOMPLETE_STOP_REASONS = new Set([
-    'pause_turn', 'max_tokens', 'length', 'MAX_TOKENS', 'OTHER',
-]);
-
 export async function agentLoop(provider, messages, model, tools, onToolCall, cwd, sendOpts) {
     let iterations = 0;
     let toolCallsTotal = 0;
@@ -571,17 +226,122 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         return true;
     };
     const maxLoopIterations = resolveSessionMaxLoopIterations(sessionRef);
+    // ---- Completion-first loop guards (worker runaway prevention) ----
+    // Step 1 (escalation ladder) + the missed-parallelism / serial-rewording
+    // steering hints live in the createSteeringLadder controller below; it owns
+    // their cumulative counters and emits at most one hint per turn.
+    // _editCount counts any executed tool call whose def lacks readOnlyHint
+    // (i.e. edit/progress: apply_patch, bash, MCP writes, skills, ...).
+    let _editCount = 0;
+    // Step 2: cross-turn identical read-only call dedup. Map keyed by
+    // signature(name + stableStringify(args)) → { count, firstIteration }.
+    // Populated only for SUCCESSFUL isEagerDispatchable (read-only) calls.
+    // Bounded to 500 entries (drop-oldest / insertion order).
+    const _crossTurnCalls = new Map();
+    const _CROSS_TURN_CAP = 500;
+    let _dedupStubTotal = 0;
+    // Step 3: worker soft-cap wrap-up state.
+    const _softCapEnabled = isWorkerSoftCapSession(sessionRef);
+    let _softCapActive = false;      // tools disabled + wrap-up injected
+    let _softCapGraceTurns = 0;      // text-only grace turns consumed (max 2)
+    let _terminatedBySoftCap = false;
+    // Hard-cap final-answer turn: one tool-less wrap-up turn granted when the
+    // hard iteration cap fires, so the session ends with text, not empty.
+    let _capFinalTurnUsed = false;
+    // Completion-first steering ladder controller. Owns the (cumulative) level-1
+    // fire count, the all-read-only / serial-single / same-file-grep streaks,
+    // and the level-2 latch. Threaded via live getters so it reads the loop's
+    // current `iterations` / `_editCount` on every call (no stale snapshots).
+    const _steeringLadder = createSteeringLadder({
+        sessionId,
+        sessionAgent,
+        tools,
+        getIterations: () => iterations,
+        softCapEnabled: _softCapEnabled,
+        getEditCount: () => _editCount,
+        readOnlyRole: String(sessionRef?.permission || sessionRef?.toolPermission || '') === 'read',
+        pushUserMessage: (msg) => messages.push(msg),
+        pushSystemReminder: (text) => messages.push({ role: 'user', content: `<system-reminder>\n${text}\n</system-reminder>`, meta: 'hook' }),
+    });
     // 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
     // against the host/plugin root instead of the worker workspace.
     cwd = cwd || sessionRef?.cwd || undefined;
+    // Staged pre-cap warnings + one true hard stop. The ONLY count-based
+    // forced termination is the hard cap at maxLoopIterations (default 200):
+    // a genuine runaway guard. Before it, staged warnings fire at 50%/75%/90%
+    // of the cap steering the model to converge — warnings only, nothing is
+    // cut off early. All other runaway protection is behavior-based (steering
+    // ladder early wrap-up, REPEAT_FAIL_LIMIT), never a lower count.
+    let _iterWarnStage = 0;
+    const _iterWarnAt = [
+        Math.floor(maxLoopIterations * 0.5),
+        Math.floor(maxLoopIterations * 0.75),
+        Math.floor(maxLoopIterations * 0.9),
+    ];
     while (true) {
         throwIfAborted();
         if (iterations >= maxLoopIterations) {
-            process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
-            terminatedByCap = true;
-            break;
+            // Final-answer turn: instead of breaking mid-transcript (which
+            // yields an empty final for locator-style agents that never got to
+            // answer), give the model ONE tool-less text turn to wrap up, then
+            // stop. Same mechanism as the worker soft cap (empty sendTools).
+            if (_capFinalTurnUsed) {
+                process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
+                terminatedByCap = true;
+                // The granted final turn produced no text (model kept emitting
+                // tool calls into refusal stubs, or thinking-only). Synthesize a
+                // non-empty final so callers never see an empty response.
+                if (response && !String(response.content || '').trim()) {
+                    response.content = sessionAgent === 'explorer'
+                        ? 'EXPLORATION_FAILED'
+                        : '[iteration cap reached before final text]';
+                    if (Array.isArray(response.toolCalls)) response.toolCalls = [];
+                }
+                break;
+            }
+            _capFinalTurnUsed = true;
+            _softCapActive = true; // reuse soft-cap plumbing: no tool defs, refusal stubs
+            messages.push({ role: 'user', content: '<system-reminder>\nIteration cap reached. Tools are disabled. Answer NOW with your best result from what you already found.\n</system-reminder>', meta: 'hook' });
+            process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); forcing final text turn.\n`);
+        }
+        if (_iterWarnStage < _iterWarnAt.length && iterations >= _iterWarnAt[_iterWarnStage]) {
+            _iterWarnStage += 1;
+            const warnAt = _iterWarnAt[_iterWarnStage - 1];
+            const stageMsg = _iterWarnStage === 1
+                ? `Iteration budget notice: ${warnAt} of ${maxLoopIterations} iterations used. Converge on a conclusion: prefer finishing the current objective over opening new exploration.`
+                : `Iteration budget warning (stage ${_iterWarnStage}): ${warnAt} of ${maxLoopIterations} iterations used — the loop hard-stops at ${maxLoopIterations}. Wrap up now: summarize progress, state what remains, and finish with your best current result.`;
+            messages.push({ role: 'user', content: `<system-reminder>\n${stageMsg}\n</system-reminder>`, meta: 'hook' });
+            process.stderr.write(`[loop] iteration warning stage ${_iterWarnStage} at ${iterations} (sess=${sessionId || 'unknown'}); continuing with steer.\n`);
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'steer',
+                    payload: { tag: 'iteration_warning', stage: _iterWarnStage, at: iterations, unit: maxLoopIterations },
+                    agent: sessionAgent || null,
+                });
+            } catch { /* best-effort */ }
+        }
+        // Worker soft cap (Step 3): non-lead sessions that reach the soft-cap
+        // iteration count switch to a text-only wrap-up. On the FIRST crossing
+        // we disable tool defs (below, via _softCapActive) and inject the
+        // assistant-visible wrap-up directive as a user message so the next
+        // send produces a final text summary. Lead/TUI sessions never enter.
+        const _earlySoftCap = _steeringLadder.earlySoftCapArmed();
+        if (_softCapEnabled && !_softCapActive && (iterations >= WORKER_SOFT_CAP_ITERATIONS || _earlySoftCap)) {
+            _softCapActive = true;
+            messages.push({ role: 'user', content: `<system-reminder>\n${SOFT_CAP_WRAPUP_MESSAGE}\n</system-reminder>`, meta: 'hook' });
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'steer',
+                    payload: { tag: 'soft_cap_wrapup', soft_cap: WORKER_SOFT_CAP_ITERATIONS, early: _earlySoftCap, level2_fires: _steeringLadder.level2FireCount },
+                    agent: sessionAgent || null,
+                });
+            } catch { /* best-effort */ }
         }
         // Drain queued steering/prompts BEFORE the
         // pre-send compact check. The compact decision must see the exact
@@ -614,6 +374,13 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             const reactivePending = reactiveOverflowRetryPending === true;
             const shouldCompact = shouldCompactForSession(messageTokensEst, compactPolicy, { forceReactive: reactivePending });
             const pressureTokens = compactionTelemetryPressureTokens(messageTokensEst, compactPolicy, { reactivePending });
+            // A pending reactive-overflow retry makes THIS compact pass the
+            // recovery from a provider overflow refusal, not the proactive
+            // pressure trigger. Tag the emitted events so telemetry can tell
+            // them apart. Hoisted above the shouldCompact branch because the
+            // PostCompact hook below fires on BOTH paths (fixes a
+            // ReferenceError on the no-compact path).
+            const compactTrigger = reactivePending ? 'reactive' : 'auto';
             const compactBudgetTokens = shouldCompact
                 ? (compactTargetBudget({ ...compactPolicy, pressureTokens }) || compactPolicy.boundaryTokens)
                 : compactPolicy.boundaryTokens;
@@ -625,13 +392,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     pressureTokens,
                 });
             } else {
-                try { opts.onStageChange?.('compacting'); } catch { /* best-effort */ }
+                try { await opts.onStageChange?.('compacting'); } catch { /* best-effort */ }
                 const compactStartedAt = Date.now();
-                // A pending reactive-overflow retry makes THIS compact pass the
-                // recovery from a provider overflow refusal, not the proactive
-                // pressure trigger. Tag the emitted events so telemetry can tell
-                // them apart, then clear the one-shot flag.
-                const compactTrigger = reactiveOverflowRetryPending ? 'reactive' : 'auto';
+                // Clear the one-shot reactive-overflow flag now that this
+                // compact pass is consuming it (compactTrigger already
+                // captured it above).
                 reactiveOverflowRetryPending = false;
                 // PreCompact: bridge to the standard hook bus before compaction
                 // runs. session-property hook (manager/loop have no bus access).
@@ -883,7 +648,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     }, compactErr);
                     }
                 }
-                try { opts.onStageChange?.('requesting'); } catch { /* best-effort */ }
+                try { await opts.onStageChange?.('requesting'); } catch { /* best-effort */ }
                 const compactChanged = messagesArrayChanged(messages, compacted);
                 if (compactChanged) {
                     messages.length = 0;
@@ -992,7 +757,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         } else {
             delete opts.toolChoice;
         }
-        const sendTools = forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools;
+        // Soft-cap wrap-up (Step 3a): once active, send NO tool definitions so
+        // the provider can only emit text. Overrides the forced-first-tool path.
+        const sendTools = _softCapActive
+            ? []
+            : (forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools);
         // Eager-dispatch queue: when the provider streams a tool-call event,
         // start read-only tools immediately so execution overlaps with the
         // remaining SSE parse. Writes and unknown tools wait until send()
@@ -1033,6 +802,17 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 const _rfg = sessionRef?._repeatFailGuard;
                 if (_rfg && _rfg.sig === _sig && _rfg.count >= REPEAT_FAIL_LIMIT) return null;
             }
+            // Cross-turn dedup also gates eager dispatch (mirror of the
+            // repeat-failure guard above): a read-only call whose (name,args)
+            // signature already ran in an EARLIER turn must NOT be eagerly
+            // re-executed — the serial for-body pushes the [cross-turn-dedup]
+            // stub instead. Without this gate startEagerRun/onToolCall would
+            // re-run the call before the serial dedup check ever sees it.
+            {
+                const _ctSig = crossTurnSignature(call.name, call.arguments);
+                const _prior = _crossTurnCalls.get(_ctSig);
+                if (_prior && _prior.firstIteration < iterations) return null;
+            }
             const toolKind = getToolKind(call.name);
             // Shared pre-dispatch deny: identical predicate runs in the
             // serial path below. If any role/permission guard would reject
@@ -1374,6 +1154,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         // tool-call-blocked vs contract-required oscillation.
         if (!response.toolCalls?.length) {
             // No tool calls. Decide between final-answer accept vs nudge.
+            // Reviewer fix: a zero-tool turn (final-pre-send steering drain or
+            // contract nudge `continue`) must not bridge the all-read-only
+            // streak across non-tool turns — that would fire level-2 early on
+            // a worker that paused to synthesize text mid-run.
+            _steeringLadder.resetAllReadOnlyStreak();
             //   - has content + non-hidden role → valid final, break.
             //   - empty content + hidden role → contract allows text-only
             //     terminal turn, break.
@@ -1447,6 +1232,37 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 : {}),
         };
         messages.push(_assistantTurnMsg);
+        // Soft-cap wrap-up (Step 3b): tools are disabled but the model still
+        // emitted tool calls. Do NOT execute them — push a refusal stub for
+        // each (after the assistant turn is appended so tool_use/tool_result
+        // pairing stays valid) and consume a grace turn. After 2 grace turns,
+        // terminate via the soft-cap path so a model that never complies stops.
+        if (_softCapActive) {
+            for (const _c of calls) {
+                pushToolResultMessage({
+                    role: 'tool',
+                    content: SOFT_CAP_REFUSAL_STUB,
+                    toolCallId: _c.id,
+                    toolKind: 'error',
+                });
+            }
+            _softCapGraceTurns += 1;
+            try {
+                appendAgentTrace({
+                    sessionId,
+                    iteration: iterations,
+                    kind: 'steer',
+                    payload: { tag: 'soft_cap_wrapup', grace_turn: _softCapGraceTurns },
+                    agent: sessionAgent || null,
+                });
+            } catch { /* best-effort */ }
+            if (_softCapGraceTurns >= 2) {
+                _terminatedBySoftCap = true;
+                break;
+            }
+            if (sessionId) updateSessionStage(sessionId, 'connecting');
+            continue;
+        }
         // Execute each tool and append results.
         //
         // Intra-turn duplicate suppression: when an LLM emits two tool_use
@@ -1501,6 +1317,42 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 });
                 continue;
             }
+            // Cross-turn identical-call stub (Step 2): a SUCCESSFUL read-only
+            // (isEagerDispatchable) call whose (name,args) signature already ran
+            // in an EARLIER turn is not re-executed — its result is unchanged and
+            // already in context. Warn at the 2nd occurrence; append the "stuck"
+            // escalation tail once the session has emitted 5+ dedup stubs total.
+            // Never applies to write/bash/MCP/skill tools (not eager-dispatchable).
+            if (isEagerDispatchable(call.name, tools)) {
+                const _ctSig = crossTurnSignature(call.name, call.arguments);
+                const _prior = _crossTurnCalls.get(_ctSig);
+                if (_prior && _prior.firstIteration < iterations) {
+                    _prior.count += 1;
+                    _dedupStubTotal += 1;
+                    const _stub = crossTurnDedupStub(call.name, _prior.firstIteration, _dedupStubTotal >= 5);
+                    pushToolResultMessage({
+                        role: 'tool',
+                        content: _stub,
+                        toolCallId: call.id,
+                    });
+                    try {
+                        appendAgentTrace({
+                            sessionId,
+                            iteration: iterations,
+                            kind: 'steer',
+                            payload: {
+                                tag: 'cross_turn_dedup',
+                                tool: call.name,
+                                occurrence: _prior.count,
+                                first_iteration: _prior.firstIteration,
+                                dedup_stub_total: _dedupStubTotal,
+                            },
+                            agent: sessionAgent || null,
+                        });
+                    } catch { /* best-effort */ }
+                    continue;
+                }
+            }
             // Cross-iteration repeat-failure guard. Distinct from the
             // intra-turn dedup above (which spans ONE assistant turn and
             // resets every turn): when the model re-issues an IDENTICAL
@@ -1660,7 +1512,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             // 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')) {
+            if (sessionRef?._scopedCacheOutcomeByCallId instanceof Map && call?.id && (!_executeOk || _resultKind === 'error')) {
                 sessionRef._scopedCacheOutcomeByCallId.delete(call.id);
             }
             // PostToolUseFailure: a tool that resolved to a failure (thrown-error
@@ -1851,7 +1703,9 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 // body via the disk path in that stub.
                 if (sessionId && _executeOk && _resultKind === 'normal') {
                     if (_scopedCacheHit === null && _isScopedCacheableTool(call.name)) {
-                        const _outcome = sessionRef?._scopedCacheOutcomeByCallId?.get(call.id);
+                        const _outcomeMap = sessionRef?._scopedCacheOutcomeByCallId instanceof Map
+                            ? sessionRef._scopedCacheOutcomeByCallId : null;
+                        const _outcome = _outcomeMap?.get(call.id);
                         setScopedToolCached({
                             sessionId,
                             toolName: _toolBare,
@@ -1861,7 +1715,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                             toolUseId: call.id,
                             complete: _outcome ? _outcome.complete : true,
                         });
-                        sessionRef?._scopedCacheOutcomeByCallId?.delete(call.id);
+                        _outcomeMap?.delete(call.id);
                     }
                     if (_readCacheHit === null && _isReadTool(call.name)) {
                         // Pass tool_use id so future cache-hits can reference the body's location in history.
@@ -1885,8 +1739,43 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                     ...(_nativeToolSearch ? { nativeToolSearch: _nativeToolSearch } : {}),
                     ...(_applyPatchUiDiff ? { uiDiff: _applyPatchUiDiff } : {}),
                 });
+                // Completion-first bookkeeping (Steps 1 & 2). Only successful
+                // executions count. Edit/progress = any executed tool whose def
+                // lacks readOnlyHint (apply_patch/bash/MCP-write/skill/...).
+                // Read-only successful calls seed the cross-turn dedup map.
+                if (_executeOk) {
+                    const _isEager = isEagerDispatchable(call.name, tools);
+                    if (_isEager) {
+                        const _ctSig = crossTurnSignature(call.name, call.arguments);
+                        if (!_crossTurnCalls.has(_ctSig)) {
+                            _crossTurnCalls.set(_ctSig, { count: 1, firstIteration: iterations });
+                            if (_crossTurnCalls.size > _CROSS_TURN_CAP) {
+                                const _oldest = _crossTurnCalls.keys().next().value;
+                                _crossTurnCalls.delete(_oldest);
+                            }
+                        }
+                    } else {
+                        // A successful mutating (non-eager) tool invalidates the
+                        // cross-turn dedup map wholesale: any prior read/grep may
+                        // now return different content, so a post-edit
+                        // verification read must NOT be stubbed as "unchanged".
+                        if (isEditProgressTool(call.name, false)) {
+                            _crossTurnCalls.clear();
+                            _editCount += 1;
+                        }
+                    }
+                }
             } catch (postErr) {
                 _postProcessOk = false;
+                // Reviewer fix: the exec itself succeeded — if it was a
+                // mutating edit-progress tool, the file changes are real even
+                // though post-processing failed, so the cross-turn dedup map
+                // must still be invalidated (otherwise a later verification
+                // read could be stubbed as "unchanged" against stale sigs).
+                if (_executeOk && !isEagerDispatchable(call.name, tools) && isEditProgressTool(call.name, false)) {
+                    _crossTurnCalls.clear();
+                    _editCount += 1;
+                }
                 // Post-processing failed AFTER a successful exec: the result is
                 // replaced with an error below, so preserve this call's full body
                 // too for a clean retry (mirrors the failed-exec path above).
@@ -1961,6 +1850,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 } catch { /* best-effort: PostToolBatch hook must never break the loop */ }
             }
         }
+        // Completion-first steering hints (missed-parallelism / all-read-only /
+        // serial-rewording). At most ONE hint per turn (priority: soft-cap >
+        // level-2 > same-file grep > level-1); soft-cap active suppresses all.
+        // The ladder controller owns the cumulative counters and streaks.
+        _steeringLadder.emitPostBatchSteering(calls, _softCapActive);
         // 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
@@ -1971,31 +1865,13 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     }
     // 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;
-    }
+    // "completed" (see classifyTerminationReason in ./loop/termination.mjs).
+    const terminationReason = classifyTerminationReason(response, {
+        terminatedByCap,
+        terminatedBySoftCap: _terminatedBySoftCap,
+        softCapActive: _softCapActive,
+        sessionAgent,
+    });
     return {
         ...response,
         usage: lastUsage || response.usage,