mixdog 0.9.174 → 1.0.0

package/src/runtime/agent/orchestrator/tools/builtin/read-tool/batch-dispatch.mjs

@@ -4,12 +4,14 @@
  * formatting), one shared byte ceiling split across distinct disk windows,
  * and the fan-out of a primary read's body to its duplicate slots.
  */
+import { stat } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
 import { imageMimeForPath } from '../read-image.mjs';
 import { readEntryCoalescedDiskWindow } from '../read-batch.mjs';
 
-// A path[] Read shares one byte ceiling. Reserve room for headers and split
-// the remaining body budget across distinct disk windows.
-function perTaskOutputBudget(entries, taskCount, options, { normalizeOutputPath, READ_MAX_OUTPUT_BYTES }) {
+// A path[] Read shares one byte ceiling. Reserve room for headers; the
+// remaining body budget is split across distinct disk windows by allocateBudgets.
+function batchBodyBudget(entries, options, { normalizeOutputPath, READ_MAX_OUTPUT_BYTES }) {
   const readCallBudget =
     Number(options?.readOutputBudgetBytes) > 0
       ? Math.min(READ_MAX_OUTPUT_BYTES, Math.trunc(Number(options.readOutputBudgetBytes)))
@@ -25,7 +27,46 @@ function perTaskOutputBudget(entries, taskCount, options, { normalizeOutputPath,
     ),
     Math.floor(readCallBudget / 2)
   );
-  return Math.max(256, Math.floor((readCallBudget - headerReserve) / Math.max(1, taskCount)));
+  return Math.max(256, readCallBudget - headerReserve);
+}
+
+const AVG_LINE_BYTES = 40;
+const MIN_LINE_BYTES = 20; // conservative: shorter lines mean more prefixes
+const LINE_PREFIX_BYTES = 8;
+const READ_RENDER_SLACK_BYTES = 1024; // trailer/marker reserve inside a child read
+
+// Estimated rendered bytes of a task: file bytes plus line-number prefixes,
+// scaled to the requested window when one is given. Unknown size → Infinity.
+async function estimateTaskBytes(entry, workDir) {
+  const st = await stat(resolvePath(workDir || '.', String(entry?.path || ''))).catch(() => null);
+  if (!st?.isFile()) return Infinity;
+  const lines = Math.max(1, st.size / AVG_LINE_BYTES);
+  let need = st.size + st.size / MIN_LINE_BYTES * LINE_PREFIX_BYTES;
+  const limit = Number(entry?.limit);
+  if (Number.isFinite(limit) && limit > 0) need *= Math.min(1, limit / lines);
+  return Math.ceil(need) + READ_RENDER_SLACK_BYTES;
+}
+
+// Water-filling: tasks needing less than the equal share get what they need;
+// the remainder is redistributed to the larger ones. Sum <= total.
+function allocateBudgets(needs, total) {
+  const budgets = new Array(needs.length).fill(0);
+  let open = needs.map((_, i) => i);
+  let remaining = total;
+  while (open.length) {
+    const share = Math.floor(remaining / open.length);
+    const small = open.filter((i) => needs[i] <= share);
+    if (small.length === 0) {
+      for (const i of open) budgets[i] = share;
+      break;
+    }
+    for (const i of small) {
+      budgets[i] = needs[i];
+      remaining -= needs[i];
+    }
+    open = open.filter((i) => needs[i] > share);
+  }
+  return budgets;
 }
 
 // Primary reads only, ordered by path then window so same-file reads chain
@@ -72,7 +113,10 @@ export async function dispatchBatchReads({
   executeChildBuiltinTool,
 }) {
   const tasks = primaryTasks(entries, readIndexFor, helpers);
-  const outputBudget = perTaskOutputBudget(entries, tasks.length, options, helpers);
+  const totalBudget = batchBodyBudget(entries, options, helpers);
+  const needs = await Promise.all(tasks.map((t) => (t.entry?.path ? estimateTaskBytes(t.entry, workDir) : 0)));
+  const allocated = allocateBudgets(needs, totalBudget);
+  const budgetByIndex = new Map(tasks.map((t, i) => [t.index, Math.max(256, allocated[i])]));
   const results = new Array(entries.length);
   const readChains = new Map();
   await Promise.all(
@@ -82,6 +126,7 @@ export async function dispatchBatchReads({
         return Promise.resolve();
       }
       const run = async () => {
+        const outputBudget = budgetByIndex.get(index);
         const readEntry = childReadEntry(entry);
         // Full image children retain their rich blocks; the aggregate
         // assembler flattens them without stringification. Other media

package/src/runtime/agent/orchestrator/tools/builtin/read-tool/batch-render.mjs

@@ -27,7 +27,7 @@ const bodyTextFor = (value) => {
     .join('\n');
 };
 
-const TRUNCATED_MARKER = /\[TRUNCATED (?:—|-) file is (\d+) lines \/ (\d+) KB\./;
+const TRUNCATED_MARKER = /\[TRUNCATED (?:—|-) (\d+) lines \/ (\d+) KB;/;
 // When `read` emitted a smart-cap marker, surface the truncation state in the
 // header so downstream skimming spots it without parsing the body.
 const truncatedSuffix = (textBody) => {

package/src/runtime/agent/orchestrator/tools/builtin/read-tool/batch-snapshot.mjs

@@ -5,6 +5,7 @@
  * the edit tools verify against.
  */
 import { readFile } from 'node:fs/promises';
+import { rangeTextOf } from '../snapshot-helpers.mjs';
 
 // Coalesced batch reads fetch the union window from disk; every caller slot
 // must be sliced back to its original request window (_orig*), not the
@@ -58,11 +59,7 @@ function deliveredRangesByPath(
 async function rawRangeHashes(fullPath, mergedRanges, { _hashText }) {
   try {
     const rawLines = (await readFile(fullPath, 'utf-8')).split('\n');
-    return mergedRanges.map((range) => {
-      const startIdx = Math.max(0, range.startLine - 1);
-      const endIdx = Math.min(rawLines.length, range.endLine);
-      return { ...range, hash: _hashText(rawLines.slice(startIdx, endIdx).join('\n')) };
-    });
+    return mergedRanges.map((range) => ({ ...range, hash: _hashText(rangeTextOf(rawLines, range)) }));
   } catch {
     /* best-effort range hashes */
     return [];

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

@@ -92,7 +92,17 @@ function executeModeRead(args, workDir, readStateScope, executeChildBuiltinTool,
   return runReadIo(() => executeSingleReadTool(args, workDir, readStateScope, options, helpers));
 }
 
-export async function executeReadTool(
+// A batch naming more distinct files than the cap was trimmed by arg-guard;
+// the last line names the dropped files so the caller can read them next.
+export async function executeReadTool(args, ...rest) {
+  const skipped = Array.isArray(args?.skipped_files) ? args.skipped_files : [];
+  if (skipped.length > 0) delete args.skipped_files;
+  const out = await executeReadToolBody(args, ...rest);
+  if (skipped.length === 0 || typeof out !== 'string') return out;
+  return `${out}\n[skipped ${skipped.length} more file(s) over the per-call limit: ${skipped.join(', ')} — read them in another call]`;
+}
+
+async function executeReadToolBody(
   args,
   workDir,
   readStateScope,

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

@@ -355,7 +355,6 @@ function _gitIgnoredEntries(directory, names) {
   return entry.observation.ignored;
 }
 
-/** Resolves once every in-flight startup git probe has finished. */
 /**
  * Boot-time prewarm: start the off-thread `git status` and `git check-ignore`
  * probes for directories a session is likely to open, so the first session's
@@ -400,6 +399,7 @@ export function prewarmGitStartupProbes(directories) {
   }
 }
 
+/** Resolves once every in-flight startup git probe has finished. */
 export async function settleGitStartupProbes() {
   await Promise.all(
     [..._repositoryChangeStates.values(), ..._gitIgnoreObservations.values()].map((entry) => entry.pending)

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

@@ -21,24 +21,12 @@ import {
   resolveSearchScope,
   uncRefusalMessage,
 } from './search-path-diagnostics.mjs';
-// Facade re-export: path-diagnostic helpers moved to search-path-diagnostics.mjs;
-// keep prior importers of search-tool.mjs unchanged.
-export {
-  _suggestIndexedPaths,
-  basePathDiagnostic,
-  buildNotFoundHint,
-  isUncOrSmbPath,
-  relativePathPrefix,
-  relativeSearchResultPath,
-  resolveSearchScope,
-  uncRefusalMessage,
-} from './search-path-diagnostics.mjs';
 import { buildGlobCacheKey, DEFAULT_IGNORE_GLOBS, rootScanIgnoreGlobs } from './search-builders.mjs';
 import { runRg, runRgWindowedLines } from './native-search-runner.mjs';
 import { markScopedCacheIncomplete } from '../../session/cache/scoped-cache-outcome.mjs';
 import { cacheGet, cacheSet, runResultCacheInFlight, statPathsForMtime, visitPathsForMtime } from './cache-layers.mjs';
 import { recordLocalSearchCacheHit } from './local-search-telemetry.mjs';
-import { uniqueStrings, coerceNonNegInt, globMtimeTiePath, resolveHeadLimit } from './lib/search-input-helpers.mjs';
+import { capPatternList, globMtimeTiePath, resolveSearchWindow, uniqueStrings } from './lib/search-input-helpers.mjs';
 import { reportToolProgress } from './lib/tool-progress.mjs';
 import { statReachable } from './fs-reachability.mjs';
 
@@ -156,13 +144,7 @@ function requestedGlobPatterns(args) {
 // cache on the original count so a capped glob never collides with an
 // exact N-pattern request or is served as the whole set.
 function capGlobPatterns(patterns, options) {
-  if (patterns.length <= GLOB_PATTERN_ARRAY_CAP) return { patterns, note: '', total: 0 };
-  if (options?.scopedCacheOutcome) markScopedCacheIncomplete(options.scopedCacheOutcome);
-  return {
-    patterns: patterns.slice(0, GLOB_PATTERN_ARRAY_CAP),
-    note: `[capped at ${GLOB_PATTERN_ARRAY_CAP} of ${patterns.length} patterns]\n`,
-    total: patterns.length,
-  };
+  return capPatternList(patterns, GLOB_PATTERN_ARRAY_CAP, options);
 }
 
 // Call-scoped stat cache: the preflight stats each root, the per-group rg
@@ -221,20 +203,6 @@ function globUncRefusal(baseEntries, patterns, resolvedForSearchRoot) {
   return null;
 }
 
-function globWindow(args) {
-  const headLimitCoerced = coerceNonNegInt(args.head_limit);
-  if (Number.isNaN(headLimitCoerced)) {
-    return {
-      error: `Error: invalid limit ${JSON.stringify(args.head_limit)}; expected a non-negative integer (0 = unlimited)`,
-    };
-  }
-  const offsetCoerced = coerceNonNegInt(args.offset);
-  if (Number.isNaN(offsetCoerced)) {
-    return { error: `Error: invalid offset ${JSON.stringify(args.offset)}; expected a non-negative integer` };
-  }
-  return { headLimit: resolveHeadLimit(headLimitCoerced, _globDefaultHeadLimit()), offset: offsetCoerced || 0 };
-}
-
 // The rg argument list for one pattern group. Explicit literal basenames
 // (no glob magic in the final segment) name a concrete file: honor rg's
 // later-glob-wins contract and let the lookup descend dependency-noise
@@ -590,7 +558,7 @@ export async function executeGlobTool(args, workDir, options = {}) {
   };
   const refusal = globUncRefusal(baseEntries, patterns, resolvedForSearchRoot);
   if (refusal) return refusal;
-  const window = globWindow(args);
+  const window = resolveSearchWindow(args, _globDefaultHeadLimit());
   if (window.error) return window.error;
   const { headLimit, offset } = window;
   const { sortMode, includeNoise, extraIgnoreGlobs } = globScanOptions(args);

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

@@ -8,18 +8,6 @@ import {
   trueCasePath,
 } from './path-utils.mjs';
 import { _suggestIndexedPaths, buildNotFoundHint, finalizeReadFamilyEnoentTail } from './search-path-diagnostics.mjs';
-// Facade re-export: path-diagnostic helpers moved to search-path-diagnostics.mjs;
-// keep prior importers of search-tool.mjs unchanged.
-export {
-  _suggestIndexedPaths,
-  basePathDiagnostic,
-  buildNotFoundHint,
-  isUncOrSmbPath,
-  relativePathPrefix,
-  relativeSearchResultPath,
-  resolveSearchScope,
-  uncRefusalMessage,
-} from './search-path-diagnostics.mjs';
 import { buildGrepCacheKey, buildGrepRgArgs } from './search-builders.mjs';
 import { runRg, runRgWindowedLines } from './native-search-runner.mjs';
 import { markScopedCacheIncomplete } from '../../session/cache/scoped-cache-outcome.mjs';

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

@@ -826,6 +826,20 @@ const SHELL_PATH_ARG_MUTATORS = new Set([
   'ln',
 ]);
 
+// find/awk are read-only by default but can delete, exec, or write files.
+// Conservative: any such action makes the stage a mutation.
+const FIND_MUTATING_FLAG_RE = /^-(?:delete|exec|execdir|ok|okdir|fprint\w*|fls)$/;
+const AWK_MUTATING_PROGRAM_RE = /\bsystem\s*\(|\b(?:print|printf)\b[^;}]*(?:>>?|\|)|\|\s*getline\b/;
+
+function isMutatingFindOrAwk(tokens) {
+  const cmd = String(tokens[0] || '').toLowerCase();
+  if (cmd === 'find') return tokens.some((tok) => FIND_MUTATING_FLAG_RE.test(String(tok)));
+  if (cmd === 'awk' || cmd === 'gawk' || cmd === 'mawk') {
+    return tokens.slice(1).some((tok) => AWK_MUTATING_PROGRAM_RE.test(String(tok)));
+  }
+  return false;
+}
+
 export async function analyzeShellCommandEffects(command, cwd) {
   const text = String(command || '').trim();
   let localCwd = resolve(cwd || process.cwd());
@@ -850,6 +864,7 @@ export async function analyzeShellCommandEffects(command, cwd) {
         if (resolved) localCwd = resolved;
         return true;
       }
+      if (isMutatingFindOrAwk(tokens)) return false;
       return SHELL_READ_ONLY_SEGMENT_RE.test(joined);
     });
     return { mutationMode: readOnly ? 'none' : 'global', paths: [], finalCwd: localCwd };
@@ -870,6 +885,10 @@ export async function analyzeShellCommandEffects(command, cwd) {
       else global = true;
       continue;
     }
+    if (isMutatingFindOrAwk(tokens)) {
+      global = true;
+      continue;
+    }
     const segmentMutates = tokens.includes('tee') || tokens.includes('>') || tokens.includes('>>');
     if (!segmentMutates && SHELL_READ_ONLY_SEGMENT_RE.test(joined)) continue;
     if (segmentMutates) {
@@ -962,6 +981,35 @@ function _teeStageHead(tokens) {
     .replace(/\.exe$/, '');
 }
 
+// The segment/pipeline splitters are not grouping-aware, so a `;` or `|`
+// inside (), {} or [] (e.g. `(a | % { $_ }) -join ','`, `try { a | sls x }`)
+// would be cut mid-group and the rewrite would break the parse. Only rewrite
+// when the head, the last segment and every stage close their own groups.
+function _groupingBalanced(text) {
+  const pairs = { ')': '(', '}': '{', ']': '[' };
+  const stack = [];
+  let quote = null;
+  let escaped = false;
+  for (const ch of String(text || '')) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\') {
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"') quote = ch;
+    else if (ch === '(' || ch === '{' || ch === '[') stack.push(ch);
+    else if (pairs[ch] && stack.pop() !== pairs[ch]) return false;
+  }
+  return stack.length === 0 && quote === null;
+}
+
 function _stageRedirectsToFile(tokens) {
   for (let i = 0; i < tokens.length; i++) {
     if (tokens[i] === '>' || tokens[i] === '>>') {
@@ -983,10 +1031,12 @@ export function buildPowerShellFilterTeePlan(command) {
   const last = segments[segments.length - 1];
   const trimmed = cmd.trimEnd();
   if (!trimmed.endsWith(last)) return null;
+  if (!_groupingBalanced(last) || !_groupingBalanced(trimmed.slice(0, trimmed.length - last.length))) return null;
   const stages = shellSplitPipelineSegments(last);
   if (stages.length < 2) return null;
   const tokenized = [];
   for (const stage of stages) {
+    if (!_groupingBalanced(stage)) return null;
     const tokens = shellTokenize(stage);
     if (!tokens || tokens.length === 0) return null;
     if (_stageRedirectsToFile(tokens)) return null;

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

@@ -291,6 +291,13 @@ export function cancelBackgroundShellJobWatch(jobId) {
   return entry.notifyCtx || null;
 }
 
+// Owner-session pending-queue delivery for a completion whose notifyFn is gone.
+function enqueueCompletionFallback(sessionId, message, meta) {
+  const visible = modelVisibleToolCompletionMessage(message, meta);
+  if (!visible) return false;
+  return enqueuePendingMessage(sessionId, markCompletionEntry(visible, { executionId: meta?.execution_id, meta })) > 0;
+}
+
 export function watchBackgroundShellJob(jobId, notifyCtx) {
   const ctx =
     notifyCtx && typeof notifyCtx.notifyFn === 'function'
@@ -338,19 +345,7 @@ export function watchBackgroundShellJob(jobId, notifyCtx) {
         resultType: 'shell_task_result',
         instruction: completion.instruction,
         context: ctx || { callerSessionId: owner },
-        enqueueFallback: (sessionId, message, meta) => {
-          const visible = modelVisibleToolCompletionMessage(message, meta);
-          if (!visible) return false;
-          return (
-            enqueuePendingMessage(
-              sessionId,
-              markCompletionEntry(visible, {
-                executionId: meta?.execution_id,
-                meta,
-              })
-            ) > 0
-          );
-        },
+        enqueueFallback: enqueueCompletionFallback,
         logPrefix: 'shell-jobs',
       });
     }
@@ -494,19 +489,7 @@ export async function reconcileRecoveredShellJobCompletions() {
         resultType: 'shell_task_result',
         instruction: completion.instruction,
         context: { callerSessionId: owner },
-        enqueueFallback: (sessionId, message, meta) => {
-          const visible = modelVisibleToolCompletionMessage(message, meta);
-          if (!visible) return false;
-          return (
-            enqueuePendingMessage(
-              sessionId,
-              markCompletionEntry(visible, {
-                executionId: meta?.execution_id,
-                meta,
-              })
-            ) > 0
-          );
-        },
+        enqueueFallback: enqueueCompletionFallback,
         logPrefix: 'shell-jobs-recovery',
       });
       if (delivered) notified += 1;

package/src/runtime/agent/orchestrator/tools/builtin/shell-lossless-compact.mjs

@@ -1,4 +1,5 @@
 import { persistToolResultArtifactSync } from '../../session/tool-result-offload.mjs';
+import { envFlag } from '../../../../shared/env.mjs';
 import { normalizeOutputPath } from './path-utils.mjs';
 
 const MIN_RAW_BYTES = 512;
@@ -6,7 +7,7 @@ const MIN_SAVED_BYTES = 384;
 const MIN_SAVED_RATIO = 0.2;
 
 function enabled() {
-  return !/^(?:0|false|no|off)$/i.test(String(process.env.MIXDOG_SHELL_LOSSLESS_COMPACT ?? '1').trim());
+  return envFlag('MIXDOG_SHELL_LOSSLESS_COMPACT', true);
 }
 
 function byteLength(value) {

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

@@ -1,7 +1,7 @@
 import { countSplitLines } from './path-utils.mjs';
 import { TOOL_OUTPUT_MAX_BYTES } from './tool-output-limit.mjs';
 
-const SHELL_OUTPUT_MAX_CHARS = TOOL_OUTPUT_MAX_BYTES;
+const SHELL_OUTPUT_MAX_BYTES = TOOL_OUTPUT_MAX_BYTES;
 
 export const SMART_BASH_MAX_LINES = 400;
 export const SMART_BASH_MAX_BYTES = TOOL_OUTPUT_MAX_BYTES;
@@ -49,7 +49,8 @@ export function renderBackgroundPartialOutput(stdout, stderr) {
 
 export function smartMiddleTruncate(content) {
   const s = typeof content === 'string' ? content : String(content ?? '');
-  if (s.length <= SMART_BASH_MAX_BYTES) {
+  const totalBytes = Buffer.byteLength(s, 'utf8');
+  if (totalBytes <= SMART_BASH_MAX_BYTES) {
     const fastLines = s.split('\n');
     if (fastLines.length <= SMART_BASH_MAX_LINES) return s;
     const head = fastLines.slice(0, SMART_BASH_HEAD_LINES).join('\n');
@@ -59,19 +60,19 @@ export function smartMiddleTruncate(content) {
   }
   const lines = s.split('\n');
   if (lines.length <= SMART_BASH_MAX_LINES) {
-    const head = s.slice(0, SMART_BASH_MAX_BYTES);
+    const head = utf8Prefix(s, SMART_BASH_MAX_BYTES);
     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);
+  const totalKb = Math.round(totalBytes / 1024);
   return `${head}\n\n... [${middle} lines omitted of ${lines.length} total / ${totalKb} KB — head and tail shown] ...\n\n${tail}`;
 }
 
 export function capShellOutput(content) {
   const s = typeof content === 'string' ? content : String(content ?? '');
-  if (s.length <= SHELL_OUTPUT_MAX_CHARS && countSplitLines(s) <= SMART_BASH_MAX_LINES) return s;
+  if (Buffer.byteLength(s, 'utf8') <= SHELL_OUTPUT_MAX_BYTES && countSplitLines(s) <= SMART_BASH_MAX_LINES) return s;
   return smartMiddleTruncate(s);
 }
 

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

@@ -43,6 +43,13 @@ export function decodeRawBufferForSnapshotCheck(rawBuf) {
   return rawBuf.subarray(enc.bomLen).toString('utf-8');
 }
 
+/** Text of a 1-based inclusive line range (endLine may be Infinity) from pre-split lines. */
+export function rangeTextOf(lines, range) {
+  const startIdx = Math.max(0, (range.startLine || 1) - 1);
+  const endIdx = range.endLine === Infinity ? lines.length : Math.min(lines.length, range.endLine);
+  return lines.slice(startIdx, endIdx).join('\n');
+}
+
 export function rangeHashesForReadRanges(content, ranges) {
   const rows = Array.isArray(ranges) ? ranges : [];
   if (rows.length === 0) return [];
@@ -58,9 +65,7 @@ export function rangeHashesForReadRanges(content, ranges) {
     const endLine = range.endLine === Infinity ? Infinity : Number(range.endLine);
     if (!Number.isFinite(startLine) || (!Number.isFinite(endLine) && endLine !== Infinity)) continue;
     if (endLine !== Infinity && endLine < startLine) continue;
-    const startIdx = startLine - 1;
-    const endIdx = endLine === Infinity ? lines.length : Math.min(lines.length, endLine);
-    out.push({ startLine, endLine, hash: hashText(lines.slice(startIdx, endIdx).join('\n')) });
+    out.push({ startLine, endLine, hash: hashText(rangeTextOf(lines, { startLine, endLine })) });
   }
   return out;
 }

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

@@ -118,26 +118,18 @@ function loadScopeFromDisk(scopeKey) {
 // Infinity to a unique sentinel on write and back on read. Shape-agnostic deep
 // clone (does NOT mutate the live in-memory snapshot objects).
 const INFINITY_SENTINEL = '__mixdog_Infinity_sentinel__';
-function _withInfinitySentinels(value) {
-  if (value === Infinity) return INFINITY_SENTINEL;
-  if (Array.isArray(value)) return value.map(_withInfinitySentinels);
+function _replaceDeep(value, from, to) {
+  if (value === from) return to;
+  if (Array.isArray(value)) return value.map((item) => _replaceDeep(item, from, to));
   if (value && typeof value === 'object') {
     const out = {};
-    for (const [k, v] of Object.entries(value)) out[k] = _withInfinitySentinels(v);
-    return out;
-  }
-  return value;
-}
-function _reviveInfinitySentinels(value) {
-  if (value === INFINITY_SENTINEL) return Infinity;
-  if (Array.isArray(value)) return value.map(_reviveInfinitySentinels);
-  if (value && typeof value === 'object') {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) out[k] = _reviveInfinitySentinels(v);
+    for (const [k, v] of Object.entries(value)) out[k] = _replaceDeep(v, from, to);
     return out;
   }
   return value;
 }
+const _withInfinitySentinels = (value) => _replaceDeep(value, Infinity, INFINITY_SENTINEL);
+const _reviveInfinitySentinels = (value) => _replaceDeep(value, INFINITY_SENTINEL, Infinity);
 
 function persistScopeSync(scopeKey, { exitDrain = false } = {}) {
   const path = snapshotScopeFilePath(scopeKey);

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

@@ -1,5 +1,5 @@
 import { hashText } from './hash-utils.mjs';
-import { normaliseRangeHashEntry, statMatchesSnapshot } from './snapshot-helpers.mjs';
+import { normaliseRangeHashEntry, rangeTextOf, statMatchesSnapshot } from './snapshot-helpers.mjs';
 
 function snapshotRangeHashRows(snapshot) {
   if (Array.isArray(snapshot?.rangeHashes)) return snapshot.rangeHashes;
@@ -54,10 +54,7 @@ export function isSnapshotStale(stat, snapshot, { fullPath = '', readCache = nul
     for (const row of rangeHashRows) {
       const r = normaliseRangeHashEntry(row);
       if (!r) continue;
-      const startIdx = Math.max(0, (r.startLine || 1) - 1);
-      const endIdx = r.endLine === Infinity ? lines.length : Math.min(lines.length, r.endLine);
-      const rangeText = lines.slice(startIdx, endIdx).join('\n');
-      if (hashText(rangeText) !== r.hash) return true;
+      if (hashText(rangeTextOf(lines, r)) !== r.hash) return true;
       verified++;
     }
     // Fail-closed: rangeHashes present but no row could be verified
@@ -87,10 +84,7 @@ export function readContentIfSnapshotHashMatches(
     for (const row of rangeHashRows) {
       const r = normaliseRangeHashEntry(row);
       if (!r) return null;
-      const startIdx = Math.max(0, (r.startLine || 1) - 1);
-      const endIdx = r.endLine === Infinity ? lines.length : Math.min(lines.length, r.endLine);
-      const rangeText = lines.slice(startIdx, endIdx).join('\n');
-      if (hashText(rangeText) !== r.hash) return null;
+      if (hashText(rangeTextOf(lines, r)) !== r.hash) return null;
     }
     return content;
   } catch {

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

@@ -1,60 +1 @@
-// Single source of truth for the model-facing tool-output byte budget.
-// read / shell / list-tree all truncate their output to this cap so the
-// context cost of any one tool call is bounded and consistent. Override with
-// MIXDOG_TOOL_OUTPUT_MAX_BYTES. Line-based sub-caps (e.g. bash max lines) stay
-// per-tool; this governs only the byte budget.
-// A positive integer from an env var, or `fallback` when unset or invalid.
-export function positiveEnvInt(name, fallback) {
-  const v = parseInt(process.env[name], 10);
-  return Number.isFinite(v) && v > 0 ? v : fallback;
-}
-export const TOOL_OUTPUT_MAX_BYTES = positiveEnvInt('MIXDOG_TOOL_OUTPUT_MAX_BYTES', 50 * 1024);
-export const LOCATOR_OUTPUT_MAX_BYTES = positiveEnvInt('MIXDOG_LOCATOR_OUTPUT_MAX_BYTES', 20 * 1024);
-// grep results stay in context for the rest of the session. 2026-09-28 cost
-// audit: only 6% of greps capped at 10KB were paged, so carrying the tail cost
-// more than the follow-up turns it saved.
-export const GREP_OUTPUT_MAX_BYTES = positiveEnvInt('MIXDOG_GREP_OUTPUT_MAX_BYTES', 5 * 1024);
-export const CODE_GRAPH_OUTPUT_MAX_BYTES = positiveEnvInt('MIXDOG_CODE_GRAPH_OUTPUT_MAX_BYTES', 30 * 1024);
-// recall/memory search returns model-facing prose blocks; uncapped multi-query
-// browses were observed injecting 42KB in one call (2026-08-05 audit). Same
-// class as locators: 20KB with a factual continuation footer.
-export const RECALL_OUTPUT_MAX_BYTES = positiveEnvInt('MIXDOG_RECALL_OUTPUT_MAX_BYTES', 20 * 1024);
-
-function _prefixByBytes(value, maxBytes) {
-  const text = String(value || '');
-  let lo = 0;
-  let hi = text.length;
-  while (lo < hi) {
-    const mid = Math.ceil((lo + hi) / 2);
-    if (Buffer.byteLength(text.slice(0, mid), 'utf8') <= maxBytes) lo = mid;
-    else hi = mid - 1;
-  }
-  return text.slice(0, lo);
-}
-
-// Preserve complete leading rows and replace the omitted tail with a
-// tool-specific continuation. Unlike the generic middle truncator this keeps
-// locator/graph output structurally usable and byte-accurate.
-export function capLineOrientedToolOutput(result, maxBytes, footerForPrefix) {
-  if (typeof result !== 'string' || !(Number(maxBytes) > 0)) return result;
-  const cap = Math.trunc(Number(maxBytes));
-  if (Buffer.byteLength(result, 'utf8') <= cap) return result;
-  const lines = result.split(/\r?\n/);
-  let lo = 0;
-  let hi = lines.length;
-  let best = '';
-  while (lo <= hi) {
-    const mid = Math.floor((lo + hi) / 2);
-    const kept = lines.slice(0, mid);
-    const footer = String(footerForPrefix?.(kept, lines) || '... [output budget reached; remainder omitted]');
-    const candidate = `${kept.join('\n')}${kept.length ? '\n' : ''}${footer}`;
-    if (Buffer.byteLength(candidate, 'utf8') <= cap) {
-      best = candidate;
-      lo = mid + 1;
-    } else {
-      hi = mid - 1;
-    }
-  }
-  if (best) return best;
-  return _prefixByBytes(String(footerForPrefix?.([], lines) || '... [output budget reached; remainder omitted]'), cap);
-}
+export * from '../../../../shared/tool-output-limit.mjs';

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

@@ -1,4 +1,4 @@
-import { performance } from 'node:perf_hooks';
+import { createIoTrace } from './io-trace.mjs';
 import { classifyResultKind } from '../session/result-classification.mjs';
 import { coerceShapeFlex, normalizeInputPath, normalizeOutputPath, resolveAgainstCwd } from './builtin/path-utils.mjs';
 import {
@@ -120,38 +120,16 @@ export { atomicWrite } from './builtin/atomic-write.mjs';
 // the same primitive without circular-import risk.
 import { pwd } from '../../../shared/user-cwd.mjs';
 
-function _ioTraceEnabled() {
-  return /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_IO_TRACE || ''));
-}
-
-function _ioTraceStart() {
-  return _ioTraceEnabled() ? performance.now() : 0;
-}
-
-function _ioTrace(event, fields = {}) {
-  if (!_ioTraceEnabled()) return;
-  try {
-    process.stderr.write(
-      `[io-trace] ${JSON.stringify({
-        event,
-        ts: Date.now(),
-        ...fields,
-      })}\n`
-    );
-  } catch {}
-}
-
-function _ioTraceDone(event, started, fields = {}) {
-  if (!started || !_ioTraceEnabled()) return;
-  _ioTrace(event, {
-    ...fields,
-    ms: Number((performance.now() - started).toFixed(3)),
-  });
-}
+// Unlike envFlag, this matcher does not trim whitespace around the value.
+const {
+  start: ioTraceStart,
+  trace: ioTrace,
+  done: ioTraceDone,
+} = createIoTrace(() => /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_IO_TRACE || '')));
 
 const _readStreamingHooks = {
-  ioTraceStart: _ioTraceStart,
-  ioTraceDone: _ioTraceDone,
+  ioTraceStart,
+  ioTraceDone,
   recordReadSnapshot: (...args) => _recordReadSnapshot(...args),
 };
 
@@ -345,7 +323,7 @@ process.on('exit', flushReadRangeIndexesSync);
 // after the default handler in those cases too, so a single hook is
 // enough for both graceful and abrupt shutdowns of the mcp child.
 
-configureReadRangeIndexTelemetry({ trace: _ioTrace, hashText: _hashText });
+configureReadRangeIndexTelemetry({ trace: ioTrace, hashText: _hashText });
 
 const _LOCATOR_BUDGET_TOOLS = new Set(['find', 'glob', 'list']);