mixdog 0.9.3 → 0.9.5

package/src/runtime/agent/orchestrator/session/loop/compact-policy.mjs

@@ -13,11 +13,17 @@ import {
     normalizeCompactType,
     DEFAULT_COMPACT_TYPE,
     DEFAULT_COMPACTION_KEEP_TOKENS,
+    CONTEXT_SHARE_RATIO,
 } from '../compact.mjs';
 import { positiveTokenInt, envFlag, envTokenInt } from './env.mjs';
+import { isAgentOwner } from '../../agent-owner.mjs';
 
 const COMPACT_SAFETY_PERCENT = 1.00;
-const COMPACT_TARGET_RATIO = 0.02;
+// Unified context-share rule (compact/constants.mjs CONTEXT_SHARE_RATIO): the
+// post-compaction target is 5% of the boundary/context window — the same 5%
+// the recall-fasttrack injection cap uses (loop.mjs recallTokenCap). One
+// number governs every "share of model context" budget.
+const COMPACT_TARGET_RATIO = CONTEXT_SHARE_RATIO;
 const COMPACT_TARGET_MIN_TOKENS = 4_000;
 const COMPACT_TARGET_MAX_TOKENS = 16_000;
 
@@ -30,7 +36,13 @@ function resolveSemanticCompactSetting(sessionRef, cfg = {}) {
     return true;
 }
 
-function resolveCompactTypeSetting(_sessionRef, cfg = {}) {
+function resolveCompactTypeSetting(sessionRef, cfg = {}) {
+    // Agent-owned sessions are ALWAYS semantic. recall-fasttrack rebuilds
+    // context from Memory recall, which is scoped to the user's main-session
+    // history — an agent's tool-loop history is not in the recall pool, so a
+    // fasttrack compact would inject unrelated main-session memories and drop
+    // the agent's own working context. Env/config overrides do not apply.
+    if (isAgentOwner(sessionRef)) return DEFAULT_COMPACT_TYPE;
     const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
         ?? process.env.MIXDOG_COMPACT_TYPE
         ?? cfg.type

package/src/runtime/agent/orchestrator/session/loop/completion-guards.mjs

@@ -0,0 +1,61 @@
+// Completion-first loop guards: escalation ladder (level-2 steering),
+// cross-turn identical read-only call dedup, and worker soft-cap wrap-up.
+// Pure string/signature helpers extracted from loop.mjs so the loop body only
+// wires state + messages. No provider/manager coupling.
+
+// Deterministic, key-sorted stringify for cross-turn call signatures. Mirrors
+// _canonicalArgs but exposed by name for the dedup signature contract.
+export function stableStringify(value) {
+    if (value == null || typeof value !== 'object') {
+        try { return JSON.stringify(value); } catch { return String(value); }
+    }
+    if (Array.isArray(value)) {
+        try { return `[${value.map(stableStringify).join(',')}]`; } catch { return String(value); }
+    }
+    try {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+    } catch { return String(value); }
+}
+
+export function crossTurnSignature(name, args) {
+    return `${name}:${stableStringify(args)}`;
+}
+
+// Tool names that are non-eager (no readOnlyHint) but are NOT edits/progress —
+// they must not reset the escalation ladder's "zero edit" condition. Skill /
+// recall / agent / task / cwd / tool_search are exploration/meta plumbing.
+const NON_PROGRESS_TOOLS = new Set(['Skill', 'recall', 'agent', 'task', 'cwd', 'tool_search']);
+
+// True when a successfully-executed tool represents real edit/progress. A tool
+// counts as progress only if its def lacks readOnlyHint (not eager) AND it is
+// not in the meta/non-progress set. apply_patch and shell/bash always count.
+export function isEditProgressTool(name, isEager) {
+    if (isEager) return false;
+    const bare = name && name.startsWith('mcp__') ? name.split('__').pop() : name;
+    if (bare === 'apply_patch' || bare === 'shell' || bare === 'bash' || bare === 'bash_session') return true;
+    return !NON_PROGRESS_TOOLS.has(bare);
+}
+
+// Step 1 — level-2 escalation steering. N = cumulative level-1 fires.
+// `readOnlyRole` swaps the edit-oriented directive for a report-oriented one:
+// read-permission sessions (reviewer-style) cannot apply_patch, so telling
+// them to edit is self-contradictory and pushes premature termination.
+export function level2SteerMessage(n, readOnlyRole = false) {
+    if (readOnlyRole) {
+        return `<system-reminder>\nYou have received this batching reminder ${n} times. Converge now: report your findings from what you have already read, or state exactly what information is missing for a verdict. A partial report with named gaps is a valid, successful completion — continued exploration is not.\n</system-reminder>`;
+    }
+    return `<system-reminder>\nYou have received this batching reminder ${n} times without making any edit. Stop exploring now: either apply_patch with what you already know, or return a blocked report stating exactly what is missing. A blocked report is a valid, successful completion — continued exploration is not.\n</system-reminder>`;
+}
+
+// Step 2 — cross-turn dedup stub. `stuck` appends the escalation tail at the
+// 5th+ dedup stub in the session.
+export function crossTurnDedupStub(name, firstIteration, stuck) {
+    let s = `[cross-turn-dedup] identical read-only \`${name}\` call already executed in iteration ${firstIteration}; its result is unchanged and already in context. Use it, or change path/offset/pattern for new information.`;
+    if (stuck) s += ` Repeated identical calls indicate you are stuck — apply what you know or return blocked.`;
+    return s;
+}
+
+// Step 3 — worker soft-cap wrap-up assistant-visible directive + refusal stub.
+export const SOFT_CAP_WRAPUP_MESSAGE = `MAXIMUM EXPLORATION BUDGET REACHED. Tools are now disabled. Respond with text only: summarize work completed so far, list remaining/incomplete items, and state what is blocking or what should be done next. This overrides all other instructions.`;
+export const SOFT_CAP_REFUSAL_STUB = `Tools are disabled: exploration budget reached. Provide your final text summary.`;

package/src/runtime/agent/orchestrator/session/loop/pre-dispatch-deny.mjs

@@ -20,9 +20,7 @@ const WORKER_DENIED_TOOLS = new Set([
     // session control.
     'agent',
     // channels module (owner/Discord-facing)
-    'reply', 'react', 'edit_message', 'download_attachment', 'fetch',
-    'schedule_status', 'trigger_schedule', 'schedule_control',
-    'activate_channel_bridge', 'reload_config', 'inject_command',
+    'reply', 'fetch',
     // host input injection
     'inject_input',
 ]);

package/src/runtime/agent/orchestrator/session/loop/recall-fasttrack.mjs

@@ -0,0 +1,275 @@
+// Recall-fasttrack compaction pipeline, extracted from loop.mjs.
+// Hydrates the session transcript into the memory pipeline (ingest_session),
+// dumps chunked/raw roots, drains cycle1 until no raw rows remain, and folds
+// the combined recall text back into a compacted message array capped at
+// CONTEXT_SHARE_RATIO of the model context window. No behavior change: this is
+// the same body that lived inline in loop.mjs, re-exported via the facade so
+// existing importers keep working.
+import { createHash } from 'crypto';
+import { executeInternalTool } from '../../internal-tools.mjs';
+import { loadConfig as loadOrchestratorConfig } from '../../config.mjs';
+import {
+    recallFastTrackCompactMessages,
+    CONTEXT_SHARE_RATIO,
+    RECALL_TOKEN_CAP_FLOOR_TOKENS,
+    drainSessionCycle1,
+    countRawPendingRows,
+} from '../compact.mjs';
+import {
+    compactDiagnosticError,
+    compactByteLength,
+    compactDebugLog,
+} from './compact-debug.mjs';
+import { positiveTokenInt } from './env.mjs';
+import { TOOL_OUTPUT_MAX_BYTES } from '../../tools/builtin/tool-output-limit.mjs';
+
+// ── Digest mode (compaction.recallDigest=true) ─────────────────────────────
+// Instead of folding the FULL chunked session dump into the compacted
+// messages (heavy: cycle1 drain + up to CONTEXT_SHARE_RATIO of the context
+// window), inject a small newest-first digest plus an instruction telling the
+// model to pull details lazily via recall(sessionId/query/period). The memory
+// DB already holds the full session (ingest_session below runs in both
+// modes), and raw rows are embedded synchronously at ingest, so recall serves
+// everything the big injection used to carry.
+// Default digest cap = the SHARED tool-output limit (TOOL_OUTPUT_MAX_BYTES,
+// 50KB default, env MIXDOG_TOOL_OUTPUT_MAX_BYTES) — the digest injection is
+// budgeted like any other tool result, not a special context share.
+// compaction.recallDigestMaxKb still overrides per-session.
+const DIGEST_DEFAULT_MAX_KB = Math.max(1, Math.floor(TOOL_OUTPUT_MAX_BYTES / 1024));
+
+// Byte-capped line-boundary truncation. Digest source is newest-first, so
+// keeping the HEAD keeps the newest turns.
+function truncateToKb(text, maxKb) {
+    const maxBytes = Math.max(1, maxKb) * 1024;
+    const s = String(text || '');
+    if (Buffer.byteLength(s, 'utf8') <= maxBytes) return s;
+    const lines = s.split('\n');
+    const out = [];
+    let used = 0;
+    for (const line of lines) {
+        const cost = Buffer.byteLength(line, 'utf8') + 1;
+        if (used + cost > maxBytes) break;
+        out.push(line);
+        used += cost;
+    }
+    return out.join('\n') + '\n[digest truncated at ' + maxKb + 'KB — pull the rest via recall]';
+}
+
+function buildRecallDigestText(sessionId, digestBody, maxKb) {
+    // No recall-usage instruction block here: the recall tool description
+    // already carries the usage-pattern cheatsheet (tool-defs.mjs), so
+    // repeating it per-compaction would be redundant injected tokens. The
+    // one-line header marks the compaction boundary and names the session id
+    // the model needs for a scoped recall.
+    return [
+        `[context compacted — session ${sessionId}]`,
+        `Full history is in memory — use the recall tool for details beyond this digest.`,
+        `Recent digest (newest first):`,
+        truncateToKb(digestBody, maxKb),
+    ].join('\n');
+}
+
+export 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;
+    }
+    // ── Digest mode: skip the dump + cycle1 drain entirely. Pull a small
+    // newest-first session browse (recall path: roots + raw fallback merged
+    // chronologically), cap it at recallDigestMaxKb, and inject it with a
+    // recall-usage instruction. The model pulls older/topical detail lazily.
+    const digestMode = sessionRef?.compaction?.recallDigest === true;
+    if (digestMode) {
+        const digestMaxKb = positiveTokenInt(sessionRef?.compaction?.recallDigestMaxKb) || DIGEST_DEFAULT_MAX_KB;
+        let digestBody = '';
+        t0 = Date.now();
+        try {
+            const browsed = await executeInternalTool('memory', {
+                action: 'search',
+                sessionId,
+                limit: positiveTokenInt(sessionRef?.compaction?.recallDigestLimit) || 30,
+                includeMembers: true,
+            }, callerCtx);
+            digestBody = typeof browsed === 'string' ? browsed : String(browsed?.text ?? browsed ?? '');
+        } catch (err) {
+            diagnostics.cycle1Error = compactDiagnosticError(err);
+            try { process.stderr.write(`[loop] recall-digest browse failed (sess=${sessionId || 'unknown'}): ${err?.message || err}\n`); } catch {}
+        }
+        diagnostics.initialDumpMs = Date.now() - t0;
+        diagnostics.cycle1Skipped = true;
+        diagnostics.cycle1SkipReason = 'digest mode';
+        diagnostics.cycle1Passes = 0;
+        const digestText = buildRecallDigestText(sessionId, digestBody, digestMaxKb);
+        diagnostics.finalRecallChars = digestText.length;
+        diagnostics.finalRecallBytes = compactByteLength(digestText);
+        const result = recallFastTrackCompactMessages(messages, compactBudgetTokens, {
+            reserveTokens: compactPolicy.reserveTokens,
+            force: true,
+            recallText: digestText,
+            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, digestMode: true } };
+        }
+        compactDebugLog('recall-digest pipeline', diagnostics);
+        return result;
+    }
+    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 || ''));
+    // Recap off = NO memory-pipeline LLM calls: skip the cycle1 drain entirely
+    // and let the dump's raw transcript lines (includeRaw:true above) ride into
+    // the injected summary as-is. Poll-on-use: re-read the flag per compact so
+    // a runtime toggle applies without restart. Default on if config read fails.
+    let recapOn = true;
+    try { recapOn = loadOrchestratorConfig({ secrets: false })?.recap?.enabled !== false; } catch { /* default on */ }
+    if (hasRawRows && !recapOn) {
+        diagnostics.cycle1Skipped = true;
+        diagnostics.cycle1SkipReason = 'recap disabled';
+        diagnostics.cycle1Passes = 0;
+        diagnostics.cycle1RawRemaining = countRawPendingRows(recallText);
+        cycle1Text = 'cycle1: skipped (recap disabled — raw transcript lines kept as-is)';
+    } else 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.error) {
+                diagnostics.cycle1Error = drained.error;
+                try { process.stderr.write(`[loop] recall-fasttrack cycle1 error (sess=${sessionId || 'unknown'}): ${drained.error}\n`); } catch {}
+            }
+            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);
+    // Recall injection (chunked-summary + raw-fallback text, combined above)
+    // never exceeds CONTEXT_SHARE_RATIO (5%) of the model context window
+    // (floor RECALL_TOKEN_CAP_FLOOR_TOKENS); the rest of the budget belongs to
+    // live conversation. Same unified 5% as the compact target ratio
+    // (compact-policy.mjs COMPACT_TARGET_RATIO). Omitted when contextWindow is
+    // unknown/0 so current no-cap behavior is preserved.
+    const _recallCapWindow = Number(compactPolicy.contextWindow) || 0;
+    const recallTokenCap = _recallCapWindow > 0
+        ? Math.max(RECALL_TOKEN_CAP_FLOOR_TOKENS, Math.floor(_recallCapWindow * CONTEXT_SHARE_RATIO))
+        : undefined;
+    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,
+        recallTokenCap,
+    });
+    diagnostics.totalMs = Date.now() - startedAt;
+    if (result && typeof result === 'object') {
+        result.diagnostics = {
+            ...(result.diagnostics || {}),
+            pipeline: diagnostics,
+        };
+    }
+    compactDebugLog('recall-fasttrack pipeline', diagnostics);
+    return result;
+}

package/src/runtime/agent/orchestrator/session/loop/steering-ladder.mjs

@@ -0,0 +1,173 @@
+// Completion-first steering ladder (worker runaway prevention), extracted from
+// loop.mjs. Owns the mutable ladder counters and the post-batch steering-hint
+// emitters. State is threaded live via a context object of getters/setters so
+// no snapshot goes stale — the loop mutates `messages`/`iterations` in place and
+// this module reads them through the accessors on each call. No behavior change:
+// the counters, thresholds, and emitted messages are verbatim from agentLoop.
+import { appendAgentTrace } from '../../agent-trace.mjs';
+import { level2SteerMessage } from './completion-guards.mjs';
+import { isEagerDispatchable } from './tool-helpers.mjs';
+
+// Consecutive ignored level-2 steers (zero edits) that force the wrap-up early.
+export const EARLY_SOFT_CAP_LEVEL2_FIRES = 3;
+
+// Build the completion-first steering-ladder controller. `ctx` supplies live
+// accessors so every read reflects the loop's current mutable state:
+//   - messages, sessionId, sessionAgent, tools           (stable refs/values)
+//   - getIterations()                                    (current iteration)
+//   - softCapEnabled                                     (constant per loop)
+//   - getEditCount()                                     (mutated by the loop)
+//   - pushSystemReminder(text)  → push a meta:'hook' user message
+//   - pushUserMessage(msg)      → push a raw user message (level-2 latch text)
+export function createSteeringLadder(ctx) {
+    const {
+        sessionId,
+        sessionAgent,
+        tools,
+        getIterations,
+        softCapEnabled,
+        getEditCount,
+    } = ctx;
+    const pushSystemReminder = ctx.pushSystemReminder;
+    const pushUserMessage = ctx.pushUserMessage;
+    // Permission-based role detection (agent names are user-definable):
+    // read-permission sessions legitimately never edit, so they get the
+    // report-oriented level-2 text and never arm the early soft-cap.
+    const readOnlyRole = ctx.readOnlyRole === true;
+
+    // Step 1: escalation ladder. _level1FireCount is CUMULATIVE (never reset)
+    // so repeated batching reminders accumulate across the whole session.
+    // _level2LatchAtIteration latches level-2 steering to at most once / 5 turns.
+    let _level1FireCount = 0;
+    let _level2LatchAtIteration = -Infinity;
+    // Independent ladder counter: consecutive turns where EVERY call is
+    // read-only (any count) with zero edits. Catches multi-call read-only
+    // turns that the single-call level-1 streak misses. Reset on any edit.
+    let _allReadOnlyStreak = 0;
+    // Tracks consecutive assistant turns that ran exactly one read-only tool
+    // call (missed parallelism). Not reset per-iteration — only by the
+    // steering-hint fire below or by a turn that batches/edits.
+    let _serialReadOnlyStreak = 0;
+    // Tracks consecutive grep calls scoped to the SAME path (any patterns) —
+    // the "serial rewording" spiral: re-grepping one file with reworded
+    // patterns instead of reading it. Only counts turns whose every call is a
+    // grep on that path; any other tool/path resets it.
+    let _sameFileGrepStreak = 0;
+    let _sameFileGrepPath = null;
+    // Early soft-cap: N ignored level-2 steers with zero edits forces the
+    // wrap-up early; any edit disarms it (level-2 requires editCount === 0).
+    let _level2FireCount = 0;
+
+    // Level-2 steering emitter shared by both ladder paths (single-call
+    // level-1 streak and the independent all-read-only streak). Sets the latch
+    // so it fires at most once per 5 turns regardless of which path triggered.
+    const _emitLevel2Steer = () => {
+        const iterations = getIterations();
+        _level2LatchAtIteration = iterations;
+        _level2FireCount += 1;
+        // When this fire arms the early soft-cap, the wrap-up injected at the
+        // next loop head supersedes the level-2 text — skip the redundant hint.
+        const _armsEarlyCap = !readOnlyRole && softCapEnabled && _level2FireCount >= EARLY_SOFT_CAP_LEVEL2_FIRES && getEditCount() === 0;
+        if (!_armsEarlyCap) pushUserMessage({ role: 'user', content: level2SteerMessage(_level1FireCount, readOnlyRole), meta: 'hook' });
+        try {
+            appendAgentTrace({
+                sessionId,
+                iteration: iterations,
+                kind: 'steer',
+                payload: { tag: 'level2_steer', level1_fires: _level1FireCount, level2_fires: _level2FireCount, edit_count: getEditCount(), all_read_only_streak: _allReadOnlyStreak },
+                agent: sessionAgent || null,
+            });
+        } catch { /* best-effort */ }
+    };
+
+    return {
+        // Loop head reads: is the early soft-cap armed?
+        get level2FireCount() { return _level2FireCount; },
+        earlySoftCapArmed() {
+            return !readOnlyRole && _level2FireCount >= EARLY_SOFT_CAP_LEVEL2_FIRES && getEditCount() === 0;
+        },
+        // Post-batch steering hint gate. `hintAlreadyFired` seeds the once-per-
+        // turn latch (soft-cap active suppresses all hints). Returns nothing;
+        // pushes at most one steering message via the ctx push callbacks.
+        emitPostBatchSteering(calls, hintAlreadyFired) {
+            const iterations = getIterations();
+            const editCount = getEditCount();
+            // Steering hint gate: at most ONE hint per turn (priority: soft-cap >
+            // level-2 > same-file grep > level-1), and none once the soft-cap
+            // wrap-up is active — its "text only" directive must not share a send
+            // with a "keep exploring" hint.
+            let _hintFiredThisTurn = hintAlreadyFired;
+            // Missed-parallelism steering: 3+ consecutive turns of a single
+            // read-only tool call suggest the model isn't batching independent
+            // lookups. Nudge once, then reset (fires again after 3 more).
+            if (calls.length === 1 && isEagerDispatchable(calls[0].name, tools)) {
+                _serialReadOnlyStreak += 1;
+                if (_serialReadOnlyStreak >= 3 && !_hintFiredThisTurn) {
+                    _serialReadOnlyStreak = 0;
+                    // Escalation ladder (Step 1). Cumulative level-1 fires are
+                    // tracked and NEVER reset. Once level-1 has fired >=3 times with
+                    // ZERO edits, escalate to level-2 steering (blocked-report is a
+                    // valid completion) instead of the batching nudge — latched to at
+                    // most once per 5 turns.
+                    _level1FireCount += 1;
+                    if (_level1FireCount >= 3 && editCount === 0 && (iterations - _level2LatchAtIteration) >= 5) {
+                        _emitLevel2Steer();
+                    } else {
+                        pushSystemReminder('Last 3 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.');
+                    }
+                    _hintFiredThisTurn = true;
+                }
+            } else {
+                _serialReadOnlyStreak = 0;
+            }
+            // Independent all-read-only escalation (audit finding): the level-1
+            // streak above only counts single-call turns, so a worker that runs
+            // 2+ read-only calls per turn escapes the ladder entirely. Track a
+            // cumulative count of consecutive turns where EVERY call is read-only
+            // (any count) and no edit has been made; at 12 such turns fire level-2
+            // directly (same once-per-5-turn latch), reset on any edit.
+            {
+                const _allReadOnly = calls.length > 0 && calls.every((c) => isEagerDispatchable(c.name, tools));
+                if (_allReadOnly && editCount === 0) {
+                    _allReadOnlyStreak += 1;
+                    if (_allReadOnlyStreak >= 12 && (iterations - _level2LatchAtIteration) >= 5 && !_hintFiredThisTurn) {
+                        _emitLevel2Steer();
+                        _hintFiredThisTurn = true;
+                    }
+                } else {
+                    _allReadOnlyStreak = 0;
+                }
+            }
+            // Serial-rewording steering: 4+ consecutive turns grepping the SAME
+            // path with reworded patterns = a search spiral that single-call
+            // batching cannot catch. Crisis-only: fires once per spiral, then
+            // resets. Read-the-file is almost always the answer at that point.
+            {
+                const _grepPathOf = (c) => {
+                    if (c?.name !== 'grep') return null;
+                    const p = c?.arguments?.path;
+                    return typeof p === 'string' && p ? p : null;
+                };
+                const _turnPaths = calls.map(_grepPathOf);
+                const _uniq = [...new Set(_turnPaths)];
+                if (_uniq.length === 1 && _uniq[0] !== null) {
+                    if (_uniq[0] === _sameFileGrepPath) _sameFileGrepStreak += 1;
+                    else { _sameFileGrepPath = _uniq[0]; _sameFileGrepStreak = 1; }
+                    if (_sameFileGrepStreak >= 4 && !_hintFiredThisTurn) {
+                        pushSystemReminder(`4+ consecutive grep turns on the same path (${_sameFileGrepPath}). Rewording patterns is not converging — read the relevant span directly (read with offset/limit) or act on what you have.`);
+                        _sameFileGrepStreak = 0;
+                        _sameFileGrepPath = null;
+                        _hintFiredThisTurn = true;
+                    }
+                } else {
+                    _sameFileGrepStreak = 0;
+                    _sameFileGrepPath = null;
+                }
+            }
+        },
+        // Reviewer fix: a zero-tool turn 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.
+        resetAllReadOnlyStreak() { _allReadOnlyStreak = 0; },
+    };
+}

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

@@ -0,0 +1,58 @@
+// Loop termination-reason classification, extracted from loop.mjs.
+// Pure function over the final response + loop-end flags. No behavior change:
+// the classification ladder is verbatim from the tail of agentLoop.
+import { HIDDEN_AGENT_NAMES } from './hidden-agents.mjs';
+
+// Stop reasons that signal the turn was cut short mid-synthesis (token cap,
+// provider pause). Empty content + one of these reasons means the worker
+// was not done. Covers Anthropic (pause_turn, max_tokens), OpenAI (length),
+// Gemini (MAX_TOKENS, OTHER), and case variants.
+export const INCOMPLETE_STOP_REASONS = new Set([
+    'pause_turn', 'max_tokens', 'length', 'MAX_TOKENS', 'OTHER',
+]);
+
+// 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 in agentLoop does (trimmed string content, or any reasoning content).
+export function classifyTerminationReason(response, {
+    terminatedByCap,
+    terminatedBySoftCap,
+    softCapActive,
+    sessionAgent,
+} = {}) {
+    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);
+    if (terminatedByCap) {
+        // Real problem regardless of hidden/public: the loop never terminated
+        // on its own contract.
+        return 'iteration_cap';
+    }
+    if (terminatedBySoftCap || softCapActive) {
+        // Worker soft-cap wrap-up path: non-lead session hit the exploration
+        // budget and was steered to a text-only finish. Distinct from the hard
+        // cap (iteration_cap) — this is an expected, budget-driven termination,
+        // not a runaway. Covers BOTH the grace-exhausted path
+        // (terminatedBySoftCap) AND the compliant path where the model emitted
+        // the final text with no more tool calls while the soft cap was active
+        // (loop ends via the no-tool-call break, so terminatedBySoftCap stays
+        // false but softCapActive is still true).
+        return 'soft_cap_wrapup';
+    }
+    if (!_finalHasContent && _finalIncompleteStop) {
+        // Cut short mid-synthesis (token cap / provider pause). Real problem
+        // for hidden agents too.
+        return 'truncated';
+    }
+    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.
+        return 'empty';
+    }
+    return undefined;
+}