mixdog 0.9.18 → 0.9.19

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

@@ -17,6 +17,27 @@ const MAX_INT = 100000;
 // defaults to 25 lines; this is only the upper bound for caller-supplied -A/-B/-C.
 export const GREP_CONTEXT_MAX = 200;
 
+// Tighter cap for CONTEXT-MODE grep (content_with_context or explicit -A/-B/-C):
+// head_limit counts MATCH BLOCKS in that mode, so ~40 blocks is already a large
+// read. Context width itself (-A/-B/-C) is deliberately NOT special-cased —
+// explicit requests are honored up to the generic GREP_CONTEXT_MAX; total
+// output stays bounded by the block clamp, the stream line cap, and the
+// tool-output byte cap.
+export const GREP_CTX_HEAD_LIMIT_MAX = 40;
+
+// Unbounded (no offset/limit) plain full reads default to this window instead of
+// pulling the whole file; the read tool's ranged-read footer then hands the
+// caller the next offset to page with.
+export const READ_GUARD_DEFAULT_LIMIT = 800;
+
+// Best-effort clamp notice channel: stash a one-line note on the args so a
+// surfacing consumer can echo it. Underscore-prefixed; ignored by executors.
+function pushClampNotice(a, msg) {
+    if (!a || typeof a !== 'object') return;
+    if (!Array.isArray(a._clampNotices)) a._clampNotices = [];
+    a._clampNotices.push(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
@@ -154,6 +175,73 @@ function coerceIntegerString(v) {
 // tells the model exactly what to do instead.
 const RANGE_SHAPED_INT_STRING = /^\d+\s*[,\-:]\s*\d+$/;
 
+// Coerce a window arg that may arrive as a real array or a JSON-stringified
+// array ("[0, 0]") into a real array; returns null when it is neither.
+function coerceWindowArray(v) {
+    if (Array.isArray(v)) return v;
+    if (typeof v === 'string') {
+        let c = coerceShapeFlex(v);
+        // Double-encoded window strings ('"[0, 0]"') unwrap to the inner
+        // string '[0, 0]' on the first flex pass — re-run once to reach the
+        // array. Lossless: only applies when the outer layer was a JSON
+        // string wrapper.
+        if (typeof c === 'string' && c !== v) c = coerceShapeFlex(c);
+        if (Array.isArray(c)) return c;
+    }
+    return null;
+}
+
+// Absorb: offset/limit arriving as parallel arrays (or JSON-stringified
+// arrays) alongside a path[] batch — zip each window onto its file as a
+// {path,offset,limit} region object, mirroring the lossless path JSON-string
+// recovery. A length-1 window array applies to every file. Per-entry integer
+// coercion/validation then runs on the resulting region objects. Length
+// mismatches zip positionally (absorb, don't hard-error); a single path with
+// multiple windows expands into regions of that path.
+function maybeZipPathWindowArrays(a) {
+    // A single-string path also zips when the windows are ARRAYS (e.g.
+    // path:'x.mjs', offset:'[0, 100]') — coerceReadFamilyPathArg unwraps
+    // one-element path[] to a string before this runs, so without this the
+    // window string would survive to the integer guard and hard-error.
+    if (typeof a.path === 'string' && a.path
+        && (coerceWindowArray(a.offset) || coerceWindowArray(a.limit))) {
+        a.path = [a.path];
+    }
+    if (!Array.isArray(a.path) || a.path.length < 1) return;
+    if (!a.path.every((e) => typeof e === 'string')) return;
+    const offs = coerceWindowArray(a.offset);
+    const lims = coerceWindowArray(a.limit);
+    if (!offs && !lims) return;
+    const n = a.path.length;
+    const pick = (arr, i) => (arr ? (arr.length === 1 ? arr[0] : arr[i]) : undefined);
+    // Single path + multiple windows -> regions of the SAME path (the model
+    // asked for several spans of one file).
+    const k = Math.max(offs?.length || 0, lims?.length || 0);
+    if (n === 1 && k > 1) {
+        const p = a.path[0];
+        a.path = Array.from({ length: k }, (_, i) => {
+            const r = { path: p };
+            const o = pick(offs, i); if (o !== undefined && o !== null) r.offset = o;
+            const l = pick(lims, i); if (l !== undefined && l !== null) r.limit = l;
+            return r;
+        });
+        delete a.offset;
+        delete a.limit;
+        return;
+    }
+    // Positional zip. Length mismatches absorb instead of hard-erroring
+    // (seen live: 3 paths + offset "[350, 1]"): missing entries mean
+    // full-file read for that path; extra window entries are dropped.
+    a.path = a.path.map((p, i) => {
+        const r = { path: p };
+        const o = pick(offs, i); if (o !== undefined && o !== null) r.offset = o;
+        const l = pick(lims, i); if (l !== undefined && l !== null) r.limit = l;
+        return r;
+    });
+    delete a.offset;
+    delete a.limit;
+}
+
 // Mutates a[field] in place when it is a lossless integer string, then
 // validates the (possibly coerced) value against [min, max].
 function checkIntInRange(a, field, min, max, opts = {}) {
@@ -167,10 +255,16 @@ function checkIntInRange(a, field, min, max, opts = {}) {
         }
     }
     if (typeof value === 'string' && RANGE_SHAPED_INT_STRING.test(value.trim())) {
-        return `Error: builtin arg "${field}" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${value}")`;
+        return `Error: "${field}" takes one integer, not a range "${value}" — use offset+limit (e.g. offset:0, limit:40)`;
+    }
+    // Soft-cap fields only: floor a fractional number (e.g. -B: 2.5) instead
+    // of erroring — intent is unambiguous for a context-line count.
+    if (opts.clamp && typeof value === 'number' && Number.isFinite(value) && !Number.isInteger(value)) {
+        value = Math.floor(value);
+        a[field] = value;
     }
     if (!isFiniteInt(value)) {
-        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)}); expected a single integer like 40`;
+        return `Error: "${field}" must be an integer (got ${describeType(value)}) — e.g. ${field}:40`;
     }
     // Soft-cap fields (grep -A/-B/-C/context): silently clamp out-of-range
     // instead of erroring — a model-guessed "300" for a 200-line cap is not
@@ -270,6 +364,18 @@ function guardGrep(a) {
     }
     // path/root (optional, string or string[])
     for (const k of ['path', 'root']) {
+        // Absorb JSON-stringified arrays ('["src","docs"]') like the read
+        // family does; an empty array ('[]' or []) means "no path filter" —
+        // drop the key so the search defaults to cwd instead of handing rg a
+        // literal "[]" path (parsed as an unclosed character class).
+        if (hasOwn(a, k) && typeof a[k] === 'string') {
+            const c = coerceShapeFlex(a[k].trim());
+            if (Array.isArray(c)) a[k] = c;
+        }
+        if (hasOwn(a, k) && Array.isArray(a[k]) && a[k].length === 0) {
+            delete a[k];
+            continue;
+        }
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
@@ -309,6 +415,22 @@ function guardGrep(a) {
             }
         }
     }
+    // Context-mode tightening: clamp head_limit (which counts MATCH BLOCKS)
+    // harder than the generic caps above, and note the clamp for surfacing.
+    // Only applies where the executor actually honors context flags — i.e.
+    // content_with_context, or content mode with explicit -A/-B/-C. In
+    // files_with_matches/count the context flags are ignored, so head_limit
+    // there means output lines/paths, not blocks — never clamp it.
+    const grepMode = a.output_mode || a.mode;
+    const hasExplicitCtx = ['-A', '-B', '-C', 'context'].some((k) => grepContextKeyPresent(a, k));
+    const isCountOrFiles = grepMode === 'files_with_matches' || grepMode === 'count';
+    if (!isCountOrFiles && (grepMode === 'content_with_context' || hasExplicitCtx)) {
+        const hl = Number(a.head_limit);
+        if (grepContextKeyPresent(a, 'head_limit') && Number.isFinite(hl) && hl > GREP_CTX_HEAD_LIMIT_MAX) {
+            a.head_limit = GREP_CTX_HEAD_LIMIT_MAX;
+            pushClampNotice(a, `notice: grep head_limit clamped to ${GREP_CTX_HEAD_LIMIT_MAX} match blocks (context mode)`);
+        }
+    }
     return null;
 }
 
@@ -339,18 +461,18 @@ function applyLineContextWindow(obj, labelPrefix) {
         return `Error: read arg "${labelPrefix}context" requires "${labelPrefix}line" to compute a window`;
     }
     if (typeof obj.line === 'string' && RANGE_SHAPED_INT_STRING.test(obj.line.trim())) {
-        return `Error: read arg "${labelPrefix}line" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${obj.line}")`;
+        return `Error: "${labelPrefix}line" takes one integer, not a range "${obj.line}" — use offset+limit (e.g. offset:0, limit:40)`;
     }
     if (!isFiniteInt(obj.line) || obj.line < 1) {
-        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)}); expected a single integer like 40`;
+        return `Error: "${labelPrefix}line" must be an integer >= 1 (got ${describeType(obj.line)}) — e.g. line:40`;
     }
     let ctx = 0;
     if (hasContext) {
         if (typeof obj.context === 'string' && RANGE_SHAPED_INT_STRING.test(obj.context.trim())) {
-            return `Error: read arg "${labelPrefix}context" takes a single integer; for a line range use offset+limit as separate integers or "path#L<start>-L<end>" in the path arg (got "${obj.context}")`;
+            return `Error: "${labelPrefix}context" takes one integer, not a range "${obj.context}" — e.g. context:5`;
         }
         if (!isFiniteInt(obj.context) || obj.context < 0) {
-            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)}); expected a single integer like 40`;
+            return `Error: "${labelPrefix}context" must be an integer >= 0 (got ${describeType(obj.context)}) — e.g. context:5`;
         }
         ctx = obj.context;
     }
@@ -361,6 +483,43 @@ function applyLineContextWindow(obj, labelPrefix) {
     return null;
 }
 
+// Item 3: an unbounded plain full read (no offset/limit/line/context/mode/n/
+// full, and a bare path with no #Lx / :line coordinate) pulls the whole file.
+// Inject a default window so large files come back capped with a next-offset
+// footer instead. Small files still return in full (limit exceeds line count);
+// explicit windows, modes, and line-spec paths are left untouched.
+function maybeCapUnboundedRead(a) {
+    // Effective path may arrive via the file_path alias; cap those the same way.
+    let pathStrs = null;
+    if (typeof a.path === 'string' && a.path.trim() !== '') {
+        pathStrs = [a.path];
+    } else if (typeof a.file_path === 'string' && a.file_path.trim() !== '') {
+        pathStrs = [a.file_path];
+    } else if (Array.isArray(a.path) && a.path.length > 0
+        && a.path.every((e) => typeof e === 'string' && e.trim() !== '')) {
+        // string[] batch: read-tool expands top-level limit uniformly onto
+        // every entry, so bare-path batches take the same default window.
+        // Region-object arrays never reach here (they carry their own
+        // windows and are rejected above when mixed with top-level limit).
+        pathStrs = a.path;
+    }
+    if (pathStrs === null) return;
+    if (a.full === true) return;
+    // symbol (and any similar body-selector) composes its own window inside the
+    // matched body — a read({path,symbol}) must never be window-truncated.
+    for (const k of ['offset', 'limit', 'line', 'context', 'n', 'mode', 'pages', 'symbol']) {
+        if (isPresent(a, k)) return;
+    }
+    // Any #Lx / :line coordinate opts the whole call out: the injected limit
+    // would override that entry's own line-spec window during per-entry
+    // normalization.
+    for (const p of pathStrs) {
+        if (p.includes('#')) return;
+        if (/:\d+(?:-\d+)?\s*$/.test(p)) return;
+    }
+    a.limit = READ_GUARD_DEFAULT_LIMIT;
+}
+
 function guardRead(a) {
     // path / file_path alias OR path may itself be array
     const hasPath = hasOwn(a, 'path') || hasOwn(a, 'file_path');
@@ -374,6 +533,9 @@ function guardRead(a) {
     if (hasOwn(a, 'path')) {
         a.path = coerceReadFamilyPathArg(a.path);
     }
+    // Absorb: parallel/JSON-stringified offset+limit arrays paired with a
+    // path[] batch — zip them into per-file region objects before validation.
+    maybeZipPathWindowArrays(a);
     // path can be string | string[] | object[]; file_path is string
     if (hasOwn(a, 'path')) {
         const p = a.path;
@@ -382,6 +544,20 @@ function guardRead(a) {
             return `Error: read arg "path" must be string, string[], or object[] (got ${describeType(p)})`;
         }
         if (Array.isArray(p)) {
+            // Absorb: a region array ({path,offset,limit}[]) carries its window
+            // per-entry; a top-level offset/limit becomes the default for any
+            // region missing its own window, then the top-level keys are dropped
+            // so they don't double-apply in the plain-read checks below.
+            const hasRegionObj = p.some((e) => e && typeof e === 'object' && !Array.isArray(e));
+            if (hasRegionObj && (isPresent(a, 'offset') || isPresent(a, 'limit'))) {
+                for (const e of p) {
+                    if (!e || typeof e !== 'object' || Array.isArray(e)) continue;
+                    if (isPresent(a, 'offset') && !isPresent(e, 'offset')) e.offset = a.offset;
+                    if (isPresent(a, 'limit') && !isPresent(e, 'limit')) e.limit = a.limit;
+                }
+                delete a.offset;
+                delete a.limit;
+            }
             for (let i = 0; i < p.length; i++) {
                 const entry = p[i];
                 if (typeof entry === 'string') continue;
@@ -400,6 +576,9 @@ function guardRead(a) {
     if (hasOwn(a, 'file_path') && !isNonEmptyString(a.file_path)) {
         return `Error: read arg "file_path" must be a non-empty string (got ${describeType(a.file_path)})`;
     }
+    // Item 3: cap unbounded full reads to a paging window (after array/region
+    // handling so batched region reads are never touched).
+    maybeCapUnboundedRead(a);
     // Read's public surface is offset/limit, but a top-level line/context pair
     // is a deterministic, lossless spelling of the same window (matching
     // read-args.mjs's internal file:line normalizer semantics); convert it
@@ -586,6 +765,19 @@ function guardCodeGraph(a) {
     if (!CODE_GRAPH_MODES.has(mode)) {
         return `Error: code_graph arg "mode" must be one of ${[...CODE_GRAPH_MODES].join('|')} (got ${JSON.stringify(a.mode)})`;
     }
+    // Absorb: file/files arriving as a JSON-stringified array
+    // (file:"[\"a.mjs\",\"b.mjs\"]") — parse to a real array so the graph
+    // lookup batches per file instead of treating the JSON text as one path.
+    for (const k of ['file', 'files']) {
+        if (hasOwn(a, k) && typeof a[k] === 'string') {
+            const c = coerceShapeFlex(a[k]);
+            if (Array.isArray(c)) a[k] = c;
+        }
+    }
+    if (Array.isArray(a.file)) {
+        a.files = Array.isArray(a.files) ? [...a.file, ...a.files] : a.file;
+        delete a.file;
+    }
     return null;
 }
 

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

@@ -114,7 +114,7 @@ export async function executeBashTool(args, workDir, options = {}) {
     const requestedCwd = args.cwd ?? args.workdir;
     const cwdResult = resolveOptionalCwd(requestedCwd, workDir);
     if (cwdResult.error) return cwdResult.error;
-    // Session cwd carry-over (Claude Code style, no live shell): when the model
+    // Session cwd carry-over (no live shell): when the model
     // passes an explicit cwd it wins and updates the store on the next probe;
     // otherwise reuse the last stored cwd for this session if it still exists.
     const _hasExplicitCwd = typeof requestedCwd === 'string' && requestedCwd.trim() !== '';
@@ -231,7 +231,15 @@ export async function executeBashTool(args, workDir, options = {}) {
     // run_in_background (already detached) or persistent sessions (handled
     // far above). Capped below the hard timeout so the 600 s upper bound
     // stays a separate, later ceiling.
-    const DEFAULT_AUTO_BACKGROUND_MS = 30_000;
+    // Soft config: reuse the sync task-wait budget (30 s, see waitForShellJob
+    // default in executeTaskTool) as the default promotion threshold. Override
+    // with MIXDOG_SHELL_AUTO_BACKGROUND_MS (positive ms). This is a soft hint,
+    // not a hard cap — the value is clamped below `timeout` so the hard ceiling
+    // stays a separate, later bound.
+    const _autoBgEnvMs = Number(process.env.MIXDOG_SHELL_AUTO_BACKGROUND_MS);
+    const DEFAULT_AUTO_BACKGROUND_MS = Number.isFinite(_autoBgEnvMs) && _autoBgEnvMs > 0
+      ? Math.floor(_autoBgEnvMs)
+      : 30_000;
     const autoBackgroundMs = runInBackground
       ? 0
       : Math.min(DEFAULT_AUTO_BACKGROUND_MS, timeout);

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

@@ -17,7 +17,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read known file path(s). Prefer grep content_with_context or code_graph anchors first. Window with numeric offset+limit. Batch paths/regions as real arrays; adjacent spans in one file = one window, not repeated calls. Dirs use list.',
+        description: 'Read known file path(s) with optional numeric offset+limit windows. Batch paths/regions as real arrays in one call. Not for directory listing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -53,7 +53,7 @@ export const BUILTIN_TOOLS = [
         name: 'shell',
         title: 'Mixdog Shell',
         annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run shell to CHANGE state or RUN programs (git/build/test/run). Never to inspect the filesystem — reading, listing, searching, existence checks use the dedicated tools, never shell. Set shell: powershell or bash. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run programs or change system state. Set shell: powershell or bash. Not for reading, listing, or searching files. ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -87,7 +87,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: 'Search file contents by text/regex in a known scope. files_with_matches/count for broad anchors, content_with_context for narrow answers. One concept → ONE grep: all variants in pattern[], scopes in path[]; parallel single-pattern greps = packing failure.',
+        description: 'Exact text/regex in a KNOWN scope. files_with_matches/count for broad anchors, content_with_context for narrow answers.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -96,30 +96,28 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Text/regex. Put synonyms in pattern[] as OR in ONE grep; no serial rewording or equivalent repeats.',
+                    description: 'Text/regex. Array = variants in one call.',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Known narrowest file/dir, or path[] to search several scopes in one call; broad scopes return paths first, then refine from returned paths.',
+                    description: 'Known file or dir. Array = several scopes.',
                 },
                 glob: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Narrow in same grep; no follow-up grep for equivalent scope changes.',
+                    description: 'Glob filter to narrow scope.',
                 },
-                output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad scope: files_with_matches/count. Narrow scope: content_with_context; answer from it, skip read unless span is not shown.' },
-                head_limit: { type: 'number', minimum: 0, description: 'Max output lines; keep small.' },
-                offset: { type: 'number', minimum: 0, description: 'Skip output lines for paging.' },
+                output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad: files_with_matches/count; narrow: content_with_context.' },
+                head_limit: { type: 'number', minimum: 0, description: 'Max results.' },
+                offset: { type: 'number', minimum: 0, description: 'Skip results for paging.' },
                 '-A': { type: 'number', minimum: 0, description: 'Lines after each match.' },
                 '-B': { type: 'number', minimum: 0, description: 'Lines before each match.' },
-                // Description nudges -C 5 on content modes — measured fix for
-                // grep→read same-file re-open round-trips (2026-07 diag).
-                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match. Content modes: pass -C 5+ so the hit is edit-ready; skipping it forces a follow-up read.' },
+                '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
             },
             required: [],
         },
@@ -128,7 +126,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by exact glob. Unknown path/name uses find. Multiple patterns/dirs = ONE call with pattern[]/path[], never parallel single-pattern calls.',
+        description: 'Find files by exact glob. Batch patterns and roots as arrays in one call.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -156,7 +154,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Find files by partial path/name. Exact structure uses glob. Returns verified paths. Multiple names = ONE call with query[].',
+        description: 'Find files by partial path/name. Returns verified paths. Batch names as query[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -177,7 +175,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 known directory entries. Use glob for broad discovery. Multiple dirs = ONE call with path[].',
+        description: 'List known directory entries. Batch dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -49,8 +49,13 @@ export function sliceReadBodyByLines(body, origOffset, origLimit) {
             : firstLine));
     const totalPart = haveTotal ? ` of ${totalNum}` : '';
     const moreToRead = haveTotal ? emittedLast < totalNum : finiteLast;
+    // Anti-fragmentation: modest remainders get the exact one-window
+    // continuation (offset+limit) instead of an open-ended "continue".
+    const _remaining = haveTotal ? totalNum - emittedLast : null;
     const continuationPart = moreToRead && Number.isFinite(emittedLast)
-        ? `; pass offset:${emittedLast} to continue`
+        ? (_remaining !== null && _remaining > 0 && _remaining <= 600
+            ? `; ${_remaining} lines left — take the rest in ONE window: offset:${emittedLast}, limit:${_remaining}`
+            : `; pass offset:${emittedLast} to continue`)
         : '';
     const newFooter = `[lines ${firstLine}-${emittedLast}${totalPart}${continuationPart}]`;
     return kept.join('\n') + (kept.length ? '\n' : '') + newFooter;

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

@@ -49,6 +49,20 @@ async function detectReadEncoding(fullPath) {
     }
 }
 
+// Reactive anti-fragmentation merge: per-session (readStateScope) memory of
+// the last requested window per file. When the next windowed read of the
+// same file starts shortly AFTER the previous window (gap <= 200 lines) and
+// the widened result stays modest (<= 400 lines), widen the request to
+// include the gap so the model never needs a third paging call.
+const _readWindowHistoryByScope = new WeakMap();
+function _readWindowHistory(scope) {
+    let m = _readWindowHistoryByScope.get(scope);
+    if (!m) { m = new Map(); _readWindowHistoryByScope.set(scope, m); }
+    return m;
+}
+const _WIDEN_GAP_MAX_LINES = 200;
+const _WIDEN_RESULT_MAX_LINES = 400;
+
 export async function executeSingleReadTool(args, workDir, readStateScope, options = {}, helpers = {}) {
     const {
         appendReadContextAdvisory,
@@ -136,12 +150,13 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
     const hasLimitArg = args.limit !== undefined && args.limit !== null;
     const hasRangeArgs = hasOffsetArg || hasLimitArg;
     const wantFull = args.full === true;
-    const offset = parseOffsetArg(args.offset);
+    let offset = parseOffsetArg(args.offset);
     // full:true bypasses the default 2000-line cap so the whole file
     // can be returned in one call; the byte-cap path below still
     // emits a compact truncation marker when rendered bytes overflow
     // READ_MAX_OUTPUT_BYTES.
-    const limit = parseLineLimitArg(args.limit, wantFull ? Infinity : 2000);
+    let limit = parseLineLimitArg(args.limit, wantFull ? Infinity : 2000);
+    let _widenNote = '';
     let st;
     let _statErr;
     try {
@@ -200,6 +215,23 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             }
         } catch { /* lstat failure is non-fatal; the original `st` is authoritative */ }
     }
+    // Reactive widen + window-history bookkeeping (ranged text reads only).
+    if (st && readStateScope && typeof readStateScope === 'object'
+        && hasOffsetArg && hasLimitArg && Number.isFinite(limit) && limit > 0) {
+        const _wins = _readWindowHistory(readStateScope);
+        const prev = _wins.get(fullPath);
+        if (prev && offset > prev.end && limit <= _WIDEN_RESULT_MAX_LINES) {
+            const gap = offset - prev.end;              // unread lines between windows
+            const mergedLines = (offset + limit) - prev.end;
+            if (gap <= _WIDEN_GAP_MAX_LINES && mergedLines <= _WIDEN_RESULT_MAX_LINES) {
+                _widenNote = `[widened: included the ${gap}-line gap after your last window (lines ${prev.start}-${prev.end}) — one span instead of another page]`;
+                offset = prev.end;
+                limit = mergedLines;
+            }
+        }
+        _wins.set(fullPath, { start: offset + 1, end: offset + limit });
+        if (_wins.size > 64) _wins.delete(_wins.keys().next().value);
+    }
     if (!st) {
         const err = _statErr;
         const redirected = await tryReadFamilyEnoentRedirect({
@@ -639,8 +671,18 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
             } else if (Buffer.byteLength(rendered, 'utf8') <= READ_MAX_OUTPUT_BYTES) {
                 const emittedStart = offset + 1;
                 const emittedEnd = offset + sliced.length;
-                const footer = `[lines ${emittedStart}-${emittedEnd} of ${lineCount}${emittedEnd < lineCount ? `; pass offset:${emittedEnd} to continue` : ''}]`;
+                // Anti-fragmentation: when the remainder is modest, hand the
+                // model the exact one-window continuation instead of inviting
+                // another small page.
+                const _remaining = lineCount - emittedEnd;
+                const _cont = emittedEnd < lineCount
+                    ? (_remaining <= 600
+                        ? `; ${_remaining} lines left — take the rest in ONE window: offset:${emittedEnd}, limit:${_remaining}`
+                        : `; pass offset:${emittedEnd} to continue`)
+                    : '';
+                const footer = `[lines ${emittedStart}-${emittedEnd} of ${lineCount}${_cont}]`;
                 out += `${out ? '\n' : ''}${footer}`;
+                if (_widenNote) out += `\n${_widenNote}`;
             }
         }
         // Smart cap. Only engages when the caller asked for

package/src/runtime/agent/orchestrator/tools/builtin/search-path-diagnostics.mjs

@@ -163,10 +163,13 @@ export function buildNotFoundHint(workDir, missingPath, actionVerb, errCode = 'E
         const parentRel = nearestExistingParentRel(workDir, missingPath);
         if (parentRel) {
             const resolvedParent = parentRel === '.' ? workDir : resolveAgainstCwd(parentRel, workDir);
-            const siblings = listSiblings(resolvedParent, 5);
+            // Compact hint: drop log/artifact noise, keep at most 3 candidates.
+            const siblings = listSiblings(resolvedParent, 12)
+                .filter((n) => !/\.(log|log\.\d+|tmp|bak)$/i.test(n))
+                .slice(0, 3);
             if (siblings.length) {
                 const shown = parentRel === '.' ? '.' : normalizeOutputPath(parentRel);
-                return ` Not found at this path; under "${shown}" try: ${siblings.map((n) => `"${n}"`).join(', ')}.`;
+                return ` Not found; under "${shown}" try: ${siblings.map((n) => `"${n}"`).join(', ')}.`;
             }
         }
     }