mixdog 0.9.93 → 0.9.94

package/src/runtime/agent/orchestrator/session/tool-batch.mjs

@@ -14,7 +14,7 @@ import { markSessionToolCall, updateSessionStage } from './manager.mjs';
 import { resolveToolSelfDeadlineMs } from '../agent-runtime/agent-progress-watchdog.mjs';
 import { classifyResultKind } from './result-classification.mjs';
 import { normalizeToolEnvelope } from './tool-envelope.mjs';
-import { maybeOffloadToolResult } from './tool-result-offload.mjs';
+import { maybeOffloadToolResultBatch } from './tool-result-offload.mjs';
 import {
     tryReadCached, setReadCached, invalidatePathForSession, markPostEdit,
     consumePostEditMark, clearReadDedupSession, extractTouchedPathsFromPatch,
@@ -93,6 +93,16 @@ export async function processToolBatch(ctx) {
         // 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 = [];
+        // Finalize together after execution so the message-level output budget
+        // can select the largest non-Read results before cache/history/UI see
+        // any body.
+        const _batchCompleted = [];
+        const _batchToolResultByCallId = new Map();
+        const _batchToolResultsWithoutId = [];
+        const _stageToolResultMessage = (message) => {
+            if (message?.toolCallId) _batchToolResultByCallId.set(message.toolCallId, message);
+            else _batchToolResultsWithoutId.push(message);
+        };
         // Ordered-mutation batch gate. Each apply_patch is an eager-dispatch
         // barrier: side effects overlap within the current segment, but no
         // later segment starts before the loop crosses the patch in model
@@ -110,7 +120,7 @@ export async function processToolBatch(ctx) {
             if (_duplicateCallIds.has(call.id)) {
                 const _firstId = _dupFirstId.get(call.id);
                 const _stub = `[intra-turn-dedup] identical read-only \`${call.name}\` call was already executed in this same assistant turn as tool_use_id=${_firstId}. The first call's tool_result is in context immediately above; skipping re-execution to save tokens. If you needed a different slice of the file, narrow the next call (different path / offset / limit / pattern) so it has a distinct signature.`;
-                pushToolResultMessage({
+                _stageToolResultMessage({
                     role: 'tool',
                     content: _stub,
                     toolCallId: call.id,
@@ -136,7 +146,7 @@ export async function processToolBatch(ctx) {
                     _prior.count += 1;
                     dedupStubTotal += 1;
                     const _stub = crossTurnDedupStub(call.name, _prior.firstIteration, dedupStubTotal >= 5);
-                    pushToolResultMessage({
+                    _stageToolResultMessage({
                         role: 'tool',
                         content: _stub,
                         toolCallId: call.id,
@@ -175,7 +185,7 @@ export async function processToolBatch(ctx) {
             {
                 const _rfg = sessionRef?._repeatFailGuard;
                 if (_rfg && _rfg.sig === _repeatFailSig && _rfg.count >= repeatFailLimit) {
-                    pushToolResultMessage({
+                    _stageToolResultMessage({
                         role: 'tool',
                         content: `[repeat-failure-guard] This exact \`${call.name}\` call (identical arguments) has already failed ${_rfg.count} times in a row; not re-executing because the result will not change. Change approach: use different arguments, a different tool, or skip this step.`,
                         toolCallId: call.id,
@@ -200,7 +210,7 @@ export async function processToolBatch(ctx) {
             // structural failure that drives retry/stop-hook behavior.
             if (_orderedMutationFailed && _isOrderedGateSkippable(call.name) && !pending.has(call.id)) {
                 if (call?.id) restoreToolCallBodyForId(assistantTurnMsg, calls, call.id);
-                pushToolResultMessage({
+                _stageToolResultMessage({
                     role: 'tool',
                     content: `[prerequisite-failed] an earlier apply_patch in this same tool batch (call index ${_orderedMutationFailed.index + 1}) failed, so this later \`${call.name}\` was skipped without starting. Re-issue it after resolving the patch failure.`,
                     toolCallId: call.id,
@@ -516,37 +526,62 @@ export async function processToolBatch(ctx) {
             if (sessionId && _isShellTool(call.name)) {
                 clearScopedToolsForSession(sessionId);
             }
-            // R17 compression pipeline — correct ordering (compress → cache → push):
-            //   1. compressToolResult: lossless ANSI/dedup/separator passes.
-            //   2. setReadCached / setScopedToolCached: cache stores the SAME result that
-            //      goes into conversation history. Cache-hit refs point to the tool_use_id
-            //      whose message body matches — no phantom full body.
-            //   3. offload → hint → message push.
-            // Offload FIRST — before compress. Large RAW output goes to a disk sidecar
-            // + ~2K preview before any in-place shrink (lossless compress) can reduce
-            // it below the offload threshold and pre-empt the sidecar. When offload
-            // fires it replaces `result` with a short preview stub (<2K) referencing
-            // the on-disk path; the later compress is a no-op on that stub. compress
-            // then only touches output that stayed inline (<= threshold).
-            // Per-tool post-processing backstop. The executeTool try/catch
-            // above terminates BEFORE offload/compress/trim/hint/cache writes/
-            // trace/messages.push, so a maybeOffloadToolResult rejection (or
-            // any downstream throw) would otherwise leave the assistant
-            // tool_use message with no matching tool result. Wrap the whole
-            // post-processing window through messages.push() in a catch; on
-            // failure push a synthetic Error: tool result for this call.id
-            // and skip the cache writes for it.
-            let _nativeToolSearch = null;
+            _batchCompleted.push({
+                call,
+                result,
+                toolStartedAt,
+                toolEndedAt,
+                toolKind,
+                resultKind: _resultKind,
+                executeOk: _executeOk,
+                readCacheHit: _readCacheHit,
+                scopedCacheHit: _scopedCacheHit,
+                crossTurnSig: _ctSig,
+                mutationEpoch: epoch.mutation,
+                nativeToolSearch: null,
+                postError: null,
+            });
+            // Soft-cancel after each tool: if close landed during execution,
+            // discard the rest of the batch and skip the next provider.send.
+            throwIfAborted();
+        }
+        for (const completed of _batchCompleted) {
             try {
-                // Offload thresholds are keyed by BARE tool name
-                // (INLINE_THRESHOLD_BY_TOOL: grep=20k, bash=30k, read=Infinity, ...),
-                // so strip the MCP prefix exactly as the cache write below does.
-                // Otherwise an mcp__..__grep name misses its 20k grep cap and
-                // silently falls back to the 50k default — per-tool limits ignored.
-                const _toolBare = _stripMcpPrefix(call.name);
-                _nativeToolSearch = parseNativeToolSearchPayload(call.name, result);
-                if (_nativeToolSearch?.summary) result = _nativeToolSearch.summary;
-                result = await maybeOffloadToolResult(sessionId, call.id, _toolBare, result);
+                completed.nativeToolSearch = parseNativeToolSearchPayload(completed.call.name, completed.result);
+                if (completed.nativeToolSearch?.summary) completed.result = completed.nativeToolSearch.summary;
+            } catch (error) {
+                completed.postError = error;
+            }
+        }
+        let _offloadStates;
+        try {
+            _offloadStates = await maybeOffloadToolResultBatch(
+                sessionId,
+                _batchCompleted.map((completed) => ({
+                    toolCallId: completed.call.id,
+                    toolName: _stripMcpPrefix(completed.call.name),
+                    result: completed.postError ? null : completed.result,
+                })),
+            );
+        } catch (error) {
+            _offloadStates = _batchCompleted.map(() => ({ result: null, error }));
+        }
+        // Assistant-message pipeline: offload → compress → trace → cache →
+        // push. The cache and transcript therefore receive the same body.
+        for (let completedIndex = 0; completedIndex < _batchCompleted.length; completedIndex += 1) {
+            const completed = _batchCompleted[completedIndex];
+            const {
+                call, toolStartedAt, toolEndedAt, toolKind,
+                executeOk: _executeOk, resultKind: _resultKind,
+                readCacheHit: _readCacheHit, scopedCacheHit: _scopedCacheHit,
+            } = completed;
+            let _ctSig = completed.crossTurnSig;
+            let result = completed.result;
+            const _nativeToolSearch = completed.nativeToolSearch;
+            try {
+                if (completed.postError) throw completed.postError;
+                if (_offloadStates[completedIndex]?.error) throw _offloadStates[completedIndex].error;
+                result = _offloadStates[completedIndex]?.result;
                 result = compressToolResult(call.name, call.arguments, result, { sessionId, toolKind });
                 traceAgentTool({
                     sessionId,
@@ -561,44 +596,37 @@ export async function processToolBatch(ctx) {
                     resultText: result,
                     cwd,
                 });
-                // Cache stores run AFTER compress+trim+offload+hint AND after all other
-                // post-processing (trace) so stored content == history content. Placing
-                // the cache writes immediately before messages.push ensures ANY throw
-                // earlier in post-processing skips the cache entirely — no stale or
-                // partial result is ever cached. Cache-hit refs pointing to an offloaded
-                // tool_use will show the offload stub; LLM can still recover the full
-                // body via the disk path in that stub.
-                if (sessionId && _executeOk && _resultKind === 'normal') {
+                // Deferred writes that predate a later mutation are skipped;
+                // immediate writes used to be invalidated by that mutation.
+                const _outcomeMap = sessionRef?._scopedCacheOutcomeByCallId instanceof Map
+                    ? sessionRef._scopedCacheOutcomeByCallId : null;
+                if (sessionId && _executeOk && _resultKind === 'normal' && completed.mutationEpoch === epoch.mutation) {
                     if (_scopedCacheHit === null && _isScopedCacheableTool(call.name)) {
-                        const _outcomeMap = sessionRef?._scopedCacheOutcomeByCallId instanceof Map
-                            ? sessionRef._scopedCacheOutcomeByCallId : null;
                         const _outcome = _outcomeMap?.get(call.id);
                         setScopedToolCached({
                             sessionId,
-                            toolName: _toolBare,
+                            toolName: _stripMcpPrefix(call.name),
                             args: call.arguments,
                             cwd,
                             content: result,
                             toolUseId: call.id,
                             complete: _outcome ? _outcome.complete : true,
                         });
-                        _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.
                         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.
+                // A successful scoped lookup from before a later mutation is
+                // intentionally not cached, but its per-call completeness
+                // record still has to be reclaimed.
+                if (_scopedCacheHit === null && _isScopedCacheableTool(call.name)) {
+                    _outcomeMap?.delete(call.id);
+                }
                 const _applyPatchUiDiff = _stripMcpPrefix(call.name) === 'apply_patch'
                     ? takeApplyPatchUiDiff(call.id)
                     : null;
-                pushToolResultMessage({
+                _stageToolResultMessage({
                     role: 'tool',
                     content: result,
                     toolCallId: call.id,
@@ -606,10 +634,6 @@ export async function processToolBatch(ctx) {
                     ...(_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 (isToolCallDedupEligible(call.name, tools)) {
@@ -621,30 +645,19 @@ export async function processToolBatch(ctx) {
                                 crossTurnCalls.delete(_oldest);
                             }
                         }
-                    } else if (!_isEager) {
-                        // 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;
-                        }
+                    } else if (!_isEager && isEditProgressTool(call.name, false)) {
+                        crossTurnCalls.clear();
+                        editCount += 1;
                     }
                 }
             } catch (postErr) {
-                // 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).
+                if (sessionRef?._scopedCacheOutcomeByCallId instanceof Map && call?.id) {
+                    sessionRef._scopedCacheOutcomeByCallId.delete(call.id);
+                }
                 if (call?.id) restoreToolCallBodyForId(assistantTurnMsg, calls, call.id);
                 const _postMsg = `Error: tool result post-processing failed for "${call.name}": ${postErr instanceof Error ? postErr.message : String(postErr)}`;
                 traceAgentToolFailure({
@@ -660,24 +673,25 @@ export async function processToolBatch(ctx) {
                     resultText: _postMsg,
                     resultKind: 'error',
                 });
-                // Always emit a matching tool result so the assistant
-                // tool_use isn't orphaned. Cache writes are placed at the
-                // end of the try block (immediately before messages.push),
-                // so ANY throw in post-processing reaches this catch before
-                // the cache is written — stale/partial results are never
-                // cached. The next read on the same path/scope re-executes
-                // naturally.
-                pushToolResultMessage({
+                _stageToolResultMessage({
                     role: 'tool',
                     content: _postMsg,
                     toolCallId: call.id,
                     toolKind: 'error',
                 });
             }
-            // Soft-cancel after each tool: if close landed during execution,
-            // discard the rest of the batch and skip the next provider.send.
             throwIfAborted();
         }
+        // Early dedup/guard skips and deferred execution results share this
+        // ordered flush so provider tool_result blocks always follow the
+        // assistant's original tool_use order.
+        for (const call of calls) {
+            const message = _batchToolResultByCallId.get(call?.id);
+            if (message) pushToolResultMessage(message);
+        }
+        for (const message of _batchToolResultsWithoutId) {
+            pushToolResultMessage(message);
+        }
         // 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

package/src/runtime/agent/orchestrator/session/tool-result-offload.mjs

@@ -10,6 +10,7 @@ const TOOL_RESULT_PREVIEW_CHARS = 2_000;
 const TOOL_RESULT_SHELL_THRESHOLD_CHARS = 30_000;
 const TOOL_RESULT_SEARCH_THRESHOLD_CHARS = 50_000;
 const TOOL_RESULT_GREP_THRESHOLD_CHARS = 20_000;
+export const TOOL_RESULT_MESSAGE_MAX_CHARS = 200_000;
 const TOOL_RESULT_OFFLOAD_PREFIX = '[tool output offloaded:';
 const OFFLOAD_PRUNE_MIN_AGE_MS = 10 * 60 * 1000;
 // clearOffloadSession only runs on a CLEAN session close, so every killed
@@ -86,6 +87,35 @@ function getOffloadThreshold(toolName) {
     return INLINE_THRESHOLD_BY_TOOL.get(key) ?? TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS;
 }
 
+const AGGREGATE_OFFLOAD_EXCLUDED_TOOLS = new Set([
+    'read',
+    'head',
+    'tail',
+    'diff',
+    'skill',
+    'skill_view',
+    'skills_list',
+]);
+
+export function isAggregateOffloadEligible(toolName, result) {
+    if (typeof result !== 'string') return false;
+    const key = String(toolName || '').toLowerCase();
+    return !AGGREGATE_OFFLOAD_EXCLUDED_TOOLS.has(key);
+}
+
+export function rankAggregateOffloadCandidates(entries) {
+    return entries
+        .map((entry, index) => ({
+            index,
+            length: typeof entry?.result === 'string' ? entry.result.length : 0,
+            eligible: isAggregateOffloadEligible(entry?.toolName, entry?.result)
+                && !String(entry?.result || '').startsWith(TOOL_RESULT_OFFLOAD_PREFIX),
+        }))
+        .filter((entry) => entry.eligible)
+        .sort((a, b) => b.length - a.length || b.index - a.index)
+        .map((entry) => entry.index);
+}
+
 // Sanitize sessionId before using it as a path segment. A raw `..` or slash
 // would let the sidecar dir — and clearOffloadSession's readdir+unlink — escape
 // the tool-results root (arbitrary .txt deletion). Strip to [A-Za-z0-9_-];
@@ -139,15 +169,17 @@ function countLines(text) {
     return lines;
 }
 
-export async function maybeOffloadToolResult(sessionId, toolCallId, toolName, result) {
+export async function maybeOffloadToolResult(sessionId, toolCallId, toolName, result, options = {}) {
     if (!sessionId || !toolCallId) return result;
     if (typeof result !== 'string') return result;
-    if (result.length <= getOffloadThreshold(toolName)) return result;
+    if (result.startsWith(TOOL_RESULT_OFFLOAD_PREFIX)) return result;
+    const force = options?.force === true;
+    if (!force && result.length <= getOffloadThreshold(toolName)) return result;
     // Keep error surfaces inline so the model can self-correct without an
     // extra read turn — but only up to the global default. A giant error
     // (e.g. a megabyte of stack/diff/dump) still offloads so it can't blow up
     // context; small errors (the overwhelming majority) stay inline.
-    if (classifyResultKind(result) === 'error'
+    if (!force && classifyResultKind(result) === 'error'
         && result.length <= TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS) return result;
 
     // Generate a safe filename — never trust toolCallId as a path component.
@@ -170,6 +202,69 @@ export async function maybeOffloadToolResult(sessionId, toolCallId, toolName, re
     return `${header}\n\n${preview}${suffix}`;
 }
 
+// Apply per-tool persistence first, then enforce the Claude Code message-level
+// budget across the remaining non-Read text results. Selection is
+// largest-first; ties prefer the latest result in the assistant tool batch.
+export async function maybeOffloadToolResultBatch(sessionId, entries, options = {}) {
+    const source = Array.isArray(entries) ? entries : [];
+    const maxChars = Number(options.maxAggregateChars) > 0
+        ? Math.trunc(Number(options.maxAggregateChars))
+        : TOOL_RESULT_MESSAGE_MAX_CHARS;
+    const applyPerToolLimits = options.applyPerToolLimits !== false;
+    const offloadResult = typeof options.offloadResult === 'function'
+        ? options.offloadResult
+        : maybeOffloadToolResult;
+    const states = source.map((entry) => ({ result: entry?.result, error: null }));
+
+    if (applyPerToolLimits) {
+        await Promise.all(source.map(async (entry, index) => {
+            try {
+                states[index].result = await offloadResult(
+                    sessionId,
+                    entry?.toolCallId,
+                    entry?.toolName,
+                    entry?.result,
+                    { force: false },
+                );
+            } catch (error) {
+                states[index].error = error;
+            }
+        }));
+    }
+
+    const inlineChars = () => states.reduce((total, state, index) => (
+        state.error || !isAggregateOffloadEligible(source[index]?.toolName, state.result)
+            ? total
+            : total + state.result.length
+    ), 0);
+    let total = inlineChars();
+    const attempted = new Set();
+    while (total > maxChars) {
+        const ranked = rankAggregateOffloadCandidates(source.map((entry, index) => ({
+            toolName: entry?.toolName,
+            result: states[index].error || attempted.has(index) ? null : states[index].result,
+        })));
+        if (ranked.length === 0) break;
+        const index = ranked[0];
+        attempted.add(index);
+        const before = states[index].result;
+        try {
+            states[index].result = await offloadResult(
+                sessionId,
+                source[index]?.toolCallId,
+                source[index]?.toolName,
+                before,
+                { force: true },
+            );
+            total += String(states[index].result || '').length - before.length;
+        } catch (error) {
+            states[index].error = error;
+            total -= before.length;
+        }
+    }
+    return states;
+}
+
 // Drop a session's offload sidecars on session close. Unlinks every
 // tool-results/<sessionId>/*.txt entry, rmdirs the directory, and drops
 // the sessionId entry from the module-level counter Map so a long-running

package/src/runtime/agent/orchestrator/tools/bash-session.mjs

@@ -112,18 +112,18 @@ function smartMiddleTruncate(content) {
         const head = fastLines.slice(0, SMART_BASH_HEAD_LINES).join('\n');
         const tail = fastLines.slice(-SMART_BASH_TAIL_LINES).join('\n');
         const middle = fastLines.length - SMART_BASH_HEAD_LINES - SMART_BASH_TAIL_LINES;
-        return `${head}\n\n... [TRUNCATED — ${middle} lines middle elided; total ${fastLines.length} lines. Rerun with tighter filters for more] ...\n\n${tail}`;
+        return `${head}\n\n... [${middle} lines omitted of ${fastLines.length} total — head and tail shown] ...\n\n${tail}`;
     }
     const lines = s.split('\n');
     if (lines.length <= SMART_BASH_MAX_LINES) {
         const head = s.slice(0, SMART_BASH_MAX_BYTES);
-        return `${head}\n\n... [TRUNCATED — output exceeded ${Math.round(SMART_BASH_MAX_BYTES / 1024)} KB on a single line] ...`;
+        return `${head}\n\n... [output exceeded ${Math.round(SMART_BASH_MAX_BYTES / 1024)} KB on a single line] ...`;
     }
     const head = lines.slice(0, SMART_BASH_HEAD_LINES).join('\n');
     const tail = lines.slice(-SMART_BASH_TAIL_LINES).join('\n');
     const middle = lines.length - SMART_BASH_HEAD_LINES - SMART_BASH_TAIL_LINES;
     const totalKb = Math.round(s.length / 1024);
-    return `${head}\n\n... [TRUNCATED — ${middle} lines middle elided; total ${lines.length} lines / ${totalKb} KB. Rerun with tighter filters for more] ...\n\n${tail}`;
+    return `${head}\n\n... [${middle} lines omitted of ${lines.length} total / ${totalKb} KB — head and tail shown] ...\n\n${tail}`;
 }
 
 function _prependDestructiveWarning(command, text) {

package/src/runtime/agent/orchestrator/tools/builtin/arg-guard.mjs

@@ -40,12 +40,12 @@ function pushClampNotice(a, msg) {
 
 // ripgrep-flavored aliases: models trained on `rg` emit short flags (-A/-B/-C),
 // long flags (--after-context / --before-context / --context), or snake/camel
-// spellings. All fold onto the canonical -A/-B/-C so a caller can write grep
+// spellings. All fold onto the canonical -A/-B/context so a caller can write grep
 // the way they would write ripgrep on the shell.
 const GREP_CONTEXT_KEY_GROUPS = [
     ['-A', ['-A', 'A', 'after', 'after_context', 'afterContext', '--after-context', 'after-context', 'afterLines', 'after_lines']],
     ['-B', ['-B', 'B', 'before', 'before_context', 'beforeContext', '--before-context', 'before-context', 'beforeLines', 'before_lines']],
-    ['-C', ['-C', 'C', 'context', 'context_lines', 'contextLines', '--context', 'contextN', 'around', 'surrounding']],
+    ['context', ['context', '-C', 'C', 'context_lines', 'contextLines', '--context', 'contextN', 'around', 'surrounding']],
 ];
 
 function grepContextKeyPresent(a, k) {
@@ -81,7 +81,7 @@ export function applyGrepContextLeadPolicy(args) {
     if (!args || typeof args !== 'object' || Array.isArray(args)) return;
     // Idempotent guard: the outer builtin guard (validateBuiltinArgs) and the
     // executor (executeGrepTool) both call this on the SAME args object. The
-    // first pass folds aliases onto -A/-B/-C and clamps; a second pass would
+    // first pass folds aliases onto -A/-B/context and clamps; a second pass would
     // recompute the same folding for no effect. Skip once applied.
     if (args._grepContextPolicyApplied) return;
     for (const [canonical, keys] of GREP_CONTEXT_KEY_GROUPS) {

package/src/runtime/agent/orchestrator/tools/builtin/bash-tool.mjs

@@ -375,7 +375,10 @@ export async function executeBashTool(args, workDir, options = {}) {
         // anywhere in the chain) used to hard-fail via foregroundLongCommandHint
         // (~22 wasted turns/14d measured). Promote them to a background task —
         // the exact remedy the deny message pointed at — same as sleep chains.
-        const _blockedSleep = detectBlockedSleepPattern(command) || detectLongForegroundReason(command);
+        // Short (2-29s) leading sleep chains stay SYNC: a 5s settle before a
+        // verification probe must not detach produce→verify into an async
+        // notification round-trip — blocking a few seconds is strictly cheaper.
+        const _blockedSleep = detectBlockedSleepPattern(command, 30) || detectLongForegroundReason(command);
         if (_blockedSleep) {
             runInBackground = true;
             autoAsyncReason = _blockedSleep;

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -115,7 +115,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Content search by literal or regex over file/dir scopes.',
+        description: 'Content search by literal or regex over file/dir scopes; matches return copy-ready raw source spans.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -143,7 +143,7 @@ export const BUILTIN_TOOLS = [
                 output_mode: { type: 'string', enum: ['content_with_context', 'files_with_matches', 'count'], description: 'content_with_context (default); files_with_matches/count for existence.' },
                 head_limit: { type: 'number', minimum: 0, description: 'Max results. Defaults to 250; 0 = unlimited.' },
                 offset: { type: 'number', minimum: 0, description: 'Skip results for paging.' },
-                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
+                context: { type: 'number', minimum: 0, description: 'Minimum surrounding lines; runtime expands within its call budget. Omit for automatic context; 0 for matches only.' },
             },
             anyOf: [
                 { required: ['pattern'] },
@@ -197,7 +197,7 @@ export const BUILTIN_TOOLS = [
                     description: 'Partial path/name words; query[] batches.',
                 },
                 path: { type: 'string', description: 'Base directory.' },
-                head_limit: { type: 'number', description: 'Max paths. Defaults to 25.' },
+                head_limit: { type: 'number', description: 'Max paths across the call. Defaults to 25.' },
             },
             required: ['query'],
             additionalProperties: false,
@@ -207,7 +207,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List directory entries; batch independent dirs as path[].',
+        description: 'List directory entries (path + type); batch independent dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {

package/src/runtime/agent/orchestrator/tools/builtin/fuzzy-match.mjs

@@ -94,7 +94,13 @@ function fuzzyScore(query, str) {
 // order but scattered mid-word, no contiguity/boundary structure) is treated
 // as noise rather than a real hit. Contiguous substring / basename matches
 // bypass the floor entirely — an exact hit must never be filtered.
-const SUBSEQUENCE_MIN_PER_CHAR = 4;
+// Measured separation for scattered junk vs real hits ("readme" probe):
+// genuine matches score ≥8/char (boundary + contiguity structure), while
+// incidental subsequences on unrelated paths land at 5–6/char — 6.5 splits
+// them. The floor is tested against the RAW subsequence score (see
+// fuzzyRank), never the +40 basename rank bonus, which otherwise vaults
+// weak basename subsequences straight past any floor.
+const SUBSEQUENCE_MIN_PER_CHAR = 6.5;
 
 // Separator/case-insensitive normalization used for the "contiguous substring"
 // strong-match test. Mirrors the query normalization in fuzzyScore so
@@ -163,7 +169,7 @@ export function fuzzyRank(query, items, limit = 0) {
     const score = prepareFuzzyScore(query);
     // Floor scales with query length: a scattered subsequence earns ~1 point
     // per char, while any contiguous run (+5/char) or word-boundary hit
-    // (+8) pushes a genuine match well past 4/char.
+    // (+8) pushes a genuine match well past 6.5/char.
     const floor = normQuery.length * SUBSEQUENCE_MIN_PER_CHAR;
     const scored = [];
     // Preserve slice's legacy coercion behavior for non-integer public callers;
@@ -185,7 +191,10 @@ export function fuzzyRank(query, items, limit = 0) {
         // Otherwise it is subsequence-only: keep it only if it clears the
         // per-char floor. Weak scattered matches (the pgAdmin-style junk that
         // merely contains the query chars in order) fall below it and drop out.
-        if (!strong && sc < floor) continue;
+        // Compare the RAW subsequence score — the +40 basename rank bonus is
+        // for ordering only and must not lift junk over the quality floor.
+        const rawSc = Math.max(pathScore ?? -Infinity, baseScore ?? -Infinity);
+        if (!strong && rawSc < floor) continue;
         const entry = { item, score: sc };
         if (bounded) retainTopRanked(scored, entry, ordinal, limit);
         else scored.push(entry);

package/src/runtime/agent/orchestrator/tools/builtin/grep-formatting.mjs

@@ -43,6 +43,28 @@ export function splitGrepCountPrefix(line) {
     return { path: text.slice(0, idx), pathEnd: idx, count: Number(count) };
 }
 
+export function parseGrepContextHeader(line) {
+    const match = /^# (.+):(\d+) \[lines (\d+)-(\d+)\]$/.exec(String(line || ''));
+    if (!match) return null;
+    const matchLine = Number(match[2]);
+    const startLine = Number(match[3]);
+    const endLine = Number(match[4]);
+    if (!Number.isSafeInteger(matchLine)
+        || !Number.isSafeInteger(startLine)
+        || !Number.isSafeInteger(endLine)
+        || startLine < 1
+        || endLine < startLine
+        || matchLine < startLine
+        || matchLine > endLine) return null;
+    return {
+        path: match[1],
+        matchLine,
+        startLine,
+        endLine,
+        sourceLineCount: endLine - startLine + 1,
+    };
+}
+
 export function normalizeGrepLine(line, pathOnly = false, outputMode = 'content', filenameOmitted = false) {
     if (process.platform !== 'win32') return line;
     // files_with_matches mode: the WHOLE line is a path, so every separator is