mixdog 0.9.18 → 0.9.20

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

@@ -53,6 +53,7 @@ import {
     normalizeGrepLine,
     splitGrepCountPrefix,
     splitGrepLinePrefix,
+    splitGrepLineNumberOnlyPrefix,
 } from './grep-formatting.mjs';
 import {
     cacheGet,
@@ -66,6 +67,8 @@ import { applyGrepContextLeadPolicy, GREP_CONTEXT_MAX, hasUnsupportedRipgrepRege
 // Default surrounding-lines window applied by output_mode:'content_with_context'
 // when the caller does not pass an explicit -A/-B/-C/context. Sized to cover a
 // typical function/block so a match arrives readable without a follow-up read.
+// Explicit -A/-B/-C is honored up to the generic GREP_CONTEXT_MAX (no tighter
+// context-mode clamp by policy); only head_limit blocks are context-clamped.
 const GREP_AUTO_CONTEXT_LINES = 25;
 
 const MIXDOG_GREP_CASE_HINT_PROBE = /^(1|true|yes|on)$/i.test(String(process.env.MIXDOG_GREP_CASE_HINT_PROBE || ''));
@@ -361,12 +364,116 @@ function buildGrepChunkMergePrefix(patternChunkCount, truncated, aggregateBudget
     return `[${parts.join('; ')}]\n`;
 }
 
+// --- context-mode match-block windowing (Parts 2 & 3) ---------------------
+// In context mode (explicit -A/-B/-C or content_with_context auto), head_limit
+// and offset count MATCH BLOCKS, not raw output lines, and truncation keeps a
+// head+tail slice with a middle marker instead of dropping the tail.
+function grepBlockMatchAnchor(line, filenameOmitted) {
+    if (filenameOmitted) {
+        const p = splitGrepLineNumberOnlyPrefix(line);
+        return p && p.delimiter === ':' ? `#${p.lineNo}` : '';
+    }
+    const s = splitGrepLinePrefix(line);
+    return s && s.delimiter === ':' ? `${s.path}\0${s.lineNo}` : '';
+}
+
+function parseGrepContextBlocks(lines, filenameOmitted) {
+    const blocks = [];
+    let pending = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === '--') { pending = []; i++; continue; }
+        const anchor = grepBlockMatchAnchor(line, filenameOmitted);
+        if (anchor) {
+            const blockLines = pending.concat([line]);
+            pending = [];
+            i++;
+            while (i < lines.length) {
+                const next = lines[i];
+                if (next === '--' || grepBlockMatchAnchor(next, filenameOmitted)) break;
+                blockLines.push(next);
+                i++;
+            }
+            blocks.push({ anchor, lines: blockLines });
+            continue;
+        }
+        pending.push(line);
+        i++;
+    }
+    return blocks;
+}
+
+function formatGrepContextOutput({ allLines, workDir, outputMode, filenameOmitted, headLimit, offset, totalKnown = true }) {
+    const norm = allLines.map((l) => (l === '--' ? '--' : relativeGrepLine(l, workDir, false, outputMode, filenameOmitted)));
+    const blocks = parseGrepContextBlocks(norm, filenameOmitted);
+    const total = blocks.length;
+    if (total === 0) return { text: '', total: 0, shown: 0, omitted: 0 };
+    // Finding 2/3: denominator is the PRE-offset grand total; on a partial rg
+    // read (stdout cap / stream cap) it is a lower bound, so print ">=T".
+    const totalStr = totalKnown ? `${total}` : `>=${total}`;
+    const afterOffset = offset > 0 ? blocks.slice(offset) : blocks;
+    if (afterOffset.length === 0) {
+        // On a partial stream (line cap / timeout) the parsed blocks are a
+        // lower bound — an offset beyond them is NOT proven past the last
+        // match, so steer toward narrowing instead of claiming "past end".
+        const text = totalKnown
+            ? `[Showing 0 of ${totalStr} matches; offset ${offset} past end]`
+            : `[Showing 0 of ${totalStr} matches (results partial); offset ${offset} is beyond the streamed window — matches past it may exist. Narrow path/glob/pattern instead of paging deeper.]`;
+        return { text, total, shown: 0, omitted: 0 };
+    }
+    const shown = headLimit === Infinity ? afterOffset.length : Math.min(headLimit, afterOffset.length);
+    const omitted = afterOffset.length - shown;
+    const render = (arr) => arr.map((b) => b.lines.join('\n'));
+    let segments;
+    let nextOffset = offset + shown;
+    if (omitted > 0 && shown > 0) {
+        // Keep head + tail so both ends of the match range stay visible.
+        const headCount = Math.max(1, Math.ceil(shown / 2));
+        const tailCount = shown - headCount;
+        const head = render(afterOffset.slice(0, headCount));
+        const tail = tailCount > 0 ? render(afterOffset.slice(afterOffset.length - tailCount)) : [];
+        segments = [...head, `…${omitted} matches omitted…`, ...tail];
+        // Paging must resume at the first OMITTED block (right after the head
+        // slice): offset+shown would permanently skip the middle blocks that
+        // the tail slice displaced. Tail blocks re-appear on later pages —
+        // duplication is acceptable, silent loss is not.
+        nextOffset = offset + headCount;
+    } else {
+        segments = render(afterOffset.slice(0, shown));
+    }
+    const notice = (omitted > 0 || !totalKnown)
+        ? `\n[Showing ${shown} of ${totalStr} matches${totalKnown ? '' : ' (results partial)'}; pass offset:${nextOffset} for more]`
+        : '';
+    return { text: segments.join('\n--\n') + notice, total, shown, omitted };
+}
+
+// Part 1: drop path:line match lines already emitted by an earlier pattern in
+// a pattern[] fan-out. Context ('-') lines and non-match lines pass through.
+function dedupeFanoutMatchLines(body, seen) {
+    const text = String(body);
+    if (/^Error:/.test(text)) return text;
+    const out = [];
+    for (const line of text.split('\n')) {
+        const s = splitGrepLinePrefix(line);
+        if (s && s.delimiter === ':') {
+            const key = `${s.path}\0${s.lineNo}`;
+            if (seen.has(key)) continue;
+            seen.add(key);
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
+
 function formatGrepOutput({ windowed, totalWindowed, totalKnown, headLimit, offset, outputMode, patterns: _patterns, beforeN, afterN, contextN, searchPath, grepResolvedPath: _grepResolvedPath, workDir, globPatterns: _globPatterns, fileType: _fileType, filenameOmitted = false, prefix = '', broadAdvisory: _broadAdvisory = true, disableContentGrouping = false }) {
     const lines = headLimit === Infinity ? windowed : windowed.slice(0, headLimit);
     const normalized = lines.map((line) => relativeGrepLine(line, workDir, outputMode === 'files_with_matches', outputMode, filenameOmitted));
     const remaining = Math.max(0, totalWindowed - lines.length);
     const shown = lines.length;
-    const total = totalWindowed;
+    // Finding 3: PRE-offset grand total so the denominator matches the
+    // context-mode notice (offset==0 leaves this unchanged).
+    const total = offset + totalWindowed;
     const scopePath = JSON.stringify(normalizeOutputPath(searchPath));
     const truncated = (remaining > 0 || !totalKnown)
         ? (totalKnown
@@ -604,6 +711,33 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
     if (fileTypes.length > 1) fileType = fileTypes;
     else if (fileTypes.length === 1) fileType = fileTypes[0];
 
+    // Part 1: pattern[] fan-out. Two or more patterns in a content search run
+    // as INDEPENDENT greps (mirroring the path[] batching above): each pattern
+    // keeps its own full head_limit budget and its own truncation notice, and
+    // identical path:line match lines are de-duplicated across patterns. The
+    // single-pattern path and the non-content modes (files_with_matches/count)
+    // keep the combined single-rg behavior. `_grepPatternFanout` guards the
+    // recursive single-pattern calls from re-entering the fan-out; the internal
+    // chunk-merge recursion is likewise skipped.
+    if (patterns.length > 1
+        && outputMode === 'content'
+        && !options._grepChunkMerge
+        && !options._grepPatternFanout) {
+        const seen = new Set();
+        const subOptions = { ...options, _grepPatternFanout: true };
+        const parts = [];
+        for (const p of patterns) {
+            let sub;
+            try {
+                sub = await executeGrepTool({ ...args, pattern: p }, workDir, executeChildBuiltinTool, readStateScope, subOptions);
+            } catch (err) {
+                sub = `Error: ${err && err.message ? err.message : err}`;
+            }
+            parts.push(`# grep pattern:${JSON.stringify(p)}\n${dedupeFanoutMatchLines(sub, seen)}`);
+        }
+        return patternCapNote + parts.join('\n\n');
+    }
+
     const patternChunkCap = multilineMode ? GREP_MULTILINE_PATTERN_CAP : GREP_ARRAY_PATTERN_CAP;
     if (patterns.length > patternChunkCap) {
         const patternChunks = chunkPatternList(patterns, patternChunkCap);
@@ -676,7 +810,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
         });
     }
 
-    const forceGrepFilename = !!options._grepChunkMerge;
+    const forceGrepFilename = !!options._grepChunkMerge || !!options._grepPatternFanout;
     const cacheKey = buildGrepCacheKey({
         patterns,
         searchPath: normalizeOutputPath(grepResolvedPath),
@@ -775,6 +909,64 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             pcre2: pcre2Mode,
             withFilename: forceGrepFilename,
         });
+        // Parts 2 & 3: context mode windows MATCH BLOCKS (not raw lines); the
+        // total match count and tail blocks come from the streamed (memory-
+        // bounded) collection below.
+        const contextMode = outputMode === 'content' && (beforeN > 0 || afterN > 0 || contextN > 0);
+        if (contextMode) {
+            // Finding 1: stream only enough lines to satisfy the block window
+            // (offset + head_limit + tail reserve), so rg is stopped early and a
+            // broad content_with_context never retains a full 20MB stdout copy.
+            // A cap hit → complete:false → partial (lower-bound) phrasing below.
+            const GREP_CONTEXT_LINE_HARD_CAP = 4000;
+            const perBlock = 2 + (beforeN || 0) + (afterN || 0) + 2 * (contextN || 0);
+            const blockBudget = headLimit === Infinity ? Infinity : offset + headLimit + 4;
+            const lineCap = blockBudget === Infinity
+                ? GREP_CONTEXT_LINE_HARD_CAP
+                : Math.min(GREP_CONTEXT_LINE_HARD_CAP, Math.max(200, blockBudget * Math.max(1, perBlock) + 8));
+            let ctxPartialSuffix = '';
+            const streamed = await runRgWindowedLines(rgArgs, { cwd: rgSpawnCwd }, { offset: 0, limit: lineCap, summaryLimit: 0 });
+            const allLines = streamed.lines;
+            let ctxTotalKnown = streamed.complete;
+            if (streamed.partial) {
+                ctxTotalKnown = false;
+                ctxPartialSuffix = streamed.timeout
+                    ? '\n[warning] rg timed out; partial results shown. Narrow path/glob/pattern for a complete result.'
+                    : streamed.rgStderr
+                    ? `\n[warning] rg exit 2 (partial results): ${String(streamed.rgStderr).trim().slice(0, 300)}`
+                    : '\n[warning] rg exit 2 (partial results)';
+            } else if (!streamed.complete) {
+                ctxPartialSuffix = `\n[warning] context output capped at ${lineCap} lines to bound memory; results partial — narrow path/glob/pattern for the full match set.`;
+            }
+            const ctx = formatGrepContextOutput({
+                allLines,
+                workDir,
+                outputMode,
+                filenameOmitted,
+                headLimit,
+                offset,
+                totalKnown: ctxTotalKnown,
+            });
+            let ctxBody = ctx.text;
+            if (!ctxBody) {
+                const patternStr = patterns.length === 1 ? JSON.stringify(patterns[0]) : JSON.stringify(patterns);
+                const globStr = normalizedGlobPatterns.length > 0 ? ` glob=${JSON.stringify(normalizedGlobPatterns)}` : '';
+                const pathInfo = grepStat.isDirectory() ? 'path exists (dir)' : 'path exists (file)';
+                ctxBody = `(no matches) pattern=${patternStr} path=${searchPath}${globStr}; ${pathInfo}`;
+            }
+            const ctxOut = patternCapNote + ctxBody + ctxPartialSuffix;
+            if (options?.scopedCacheOutcome && (!ctxTotalKnown || ctx.omitted > 0)) {
+                markScopedCacheIncomplete(options.scopedCacheOutcome);
+            }
+            recordGrepReadSnapshot(grepStat);
+            if (ctxTotalKnown && ctx.omitted === 0) {
+                cacheSet(cacheKey, ctxOut, { scopes: [grepResolvedPath] });
+            }
+            if (typeof options?.onProgress === 'function') {
+                try { options.onProgress(`found ${ctx.total} matches`); } catch { /* best-effort */ }
+            }
+            return ctxOut;
+        }
         let windowed;
         let totalWindowed = 0;
         let totalKnown = true;
@@ -832,7 +1024,7 @@ export async function executeGrepTool(args, workDir, executeChildBuiltinTool, re
             globPatterns: normalizedGlobPatterns,
             fileType,
             filenameOmitted,
-            disableContentGrouping: !!options._grepChunkMerge,
+            disableContentGrouping: !!options._grepChunkMerge || !!options._grepPatternFanout,
         });
         if (!body) {
             const pathInfo = grepStat.isDirectory() ? 'path exists (dir)' : 'path exists (file)';

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

@@ -1,8 +1,41 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs';
 import * as fsPromises from 'fs/promises';
-import { join } from 'path';
+import { basename, join } from 'path';
 import { getPluginData } from '../../config.mjs';
 
+// Bounded tail kept for a job's spilled stdout/stderr. A flooding job could
+// otherwise leave a 100MB+ .stdout.log/.stderr.log sitting for up to the 24h
+// stale TTL. Trimming to a few-MB tail preserves the most recent output
+// (where the final error/exit context lives) while capping on-disk growth.
+const SHELL_JOB_SPILL_MAX_BYTES = 4 * 1024 * 1024;
+const SHELL_JOB_SPILL_KEEP_BYTES = 4 * 1024 * 1024;
+
+// Tail-trim a single spill log in place: if it exceeds maxBytes, rewrite it
+// keeping only the last keepBytes. Sync, best-effort, no-op on a missing file.
+// Mirrors rotateBoundedLog in src/lib/mixdog-debug.cjs. Returns true if trimmed.
+export function trimShellJobSpillFile(filePath, maxBytes = SHELL_JOB_SPILL_MAX_BYTES, keepBytes = SHELL_JOB_SPILL_KEEP_BYTES) {
+    try {
+        const st = statSync(filePath);
+        if (st.size <= maxBytes) return false;
+        const buf = readFileSync(filePath);
+        writeFileSync(filePath, buf.subarray(Math.max(0, buf.length - keepBytes)));
+        return true;
+    } catch { return false; }
+}
+
+// Trim a completed job's stdout+stderr spill files to a bounded tail. Called on
+// every terminal transition so a completed flooding job can never leave a
+// 100MB spill behind for the sweep to reclaim a day later. Uses the detail's
+// recorded paths — adopted foreground jobs spill to shell-output/, not the
+// shell-jobs dir — and dedupes when mergeStderr collapses both onto stdoutPath.
+export function trimShellJobSpill(detail) {
+    if (!detail) return;
+    const stdoutPath = detail.stdoutPath || shellJobStdoutPath(detail.jobId);
+    const stderrPath = detail.stderrPath || shellJobStderrPath(detail.jobId);
+    trimShellJobSpillFile(stdoutPath);
+    if (stderrPath && stderrPath !== stdoutPath) trimShellJobSpillFile(stderrPath);
+}
+
 // One-shot sweep of stale shell-job artefacts. Each backgrounded `bash`
 // emits five files (.json/.done/.exit/.stdout.log/.stderr.log); the .done
 // flag is written when the job exits, so a .done file older than
@@ -82,6 +115,79 @@ async function sweepStaleShellJobs(dir) {
         ),
         ...ownerMarkers.map((n) => fsPromises.unlink(join(dir, n)).catch(() => {})),
     ]);
+    // Size enforcement for survivors: a completed flooding job whose .done is
+    // still younger than the stale cutoff isn't expired above, yet its spill
+    // can hold 100MB+ for up to a day. Proof-of-death is the .done marker (NOT
+    // mtime): mtime gating both truncated LIVE-but-quiet jobs whose writer
+    // handle is still open — sparse-regrow corruption — AND waited a full day
+    // to trim completed floods. Gating on doneSet means we only rewrite a file
+    // whose producer has provably exited, which also retries kill-path trims
+    // that failed silently while the killed child still held the redirect
+    // handle on Windows (trimShellJobSpillFile swallows the lock error).
+    await Promise.all(names.map(async (name) => {
+        const isStdout = name.endsWith('.stdout.log');
+        if (!isStdout && !name.endsWith('.stderr.log')) return;
+        const jobId = name.slice(0, -11); // both suffixes are 11 chars
+        if (expiredSet.has(jobId)) return; // already unlinked above
+        if (!doneSet.has(jobId)) return;   // no completion marker → maybe live, never touch
+        const p = join(dir, name);
+        try {
+            const st = await fsPromises.stat(p);
+            if (st.size <= SHELL_JOB_SPILL_MAX_BYTES) return;
+            const buf = await fsPromises.readFile(p);
+            await fsPromises.writeFile(p, buf.subarray(Math.max(0, buf.length - SHELL_JOB_SPILL_KEEP_BYTES)));
+        } catch {}
+    }));
+    sweepStaleShellOutput(dir, names);
+}
+
+// Sibling GC for spill files under $PLUGIN_DATA/shell-output/. TaskOutput
+// (shell-command.mjs) spills foreground stdout/stderr there as <taskId>.stdout
+// /.stderr once past the inline cap; a KEPT foreground spill (child dead at
+// settle) or an adopted job's leftover then sits at up to the 100MB disk cap
+// with no sweep of its own. Proof-of-death required before touching a file
+// (an open writer handle is the only corruption/ENOENT-to-a-reader risk): a
+// file is skipped iff some shell-job with a live pid and no .done references
+// it. pid-reuse false positives err toward NOT touching. Dead files past the
+// stale TTL are removed; oversized dead files are trimmed to a bounded tail.
+async function sweepStaleShellOutput(shellJobsDir, jobNames) {
+    const outDir = join(getPluginData(), 'shell-output');
+    let outNames;
+    try { outNames = await fsPromises.readdir(outDir); } catch { return; }
+    if (outNames.length === 0) return;
+    const doneSet = new Set(jobNames.filter(n => n.endsWith('.done')).map(n => n.slice(0, -5)));
+    const liveSpill = new Set();
+    await Promise.all(jobNames.map(async (name) => {
+        if (!name.endsWith('.json')) return;
+        const jobId = name.slice(0, -5);
+        if (doneSet.has(jobId)) return; // completed → its spill is provably dead
+        try {
+            const detail = JSON.parse(await fsPromises.readFile(join(shellJobsDir, name), 'utf-8'));
+            const pid = Number(detail?.pid);
+            let alive = true; // unknown/invalid pid → conservative: treat as live
+            if (Number.isFinite(pid) && pid > 0) {
+                try { process.kill(pid, 0); alive = true; }   // running (or EPERM)
+                catch (e) { alive = e?.code !== 'ESRCH'; }     // ESRCH → dead
+            }
+            if (!alive) return;
+            for (const key of ['stdoutPath', 'stderrPath']) {
+                const p = detail?.[key];
+                if (typeof p === 'string' && p) liveSpill.add(basename(p));
+            }
+        } catch {}
+    }));
+    const cutoff = Date.now() - SHELL_JOB_STALE_MS;
+    await Promise.all(outNames.map(async (name) => {
+        if (liveSpill.has(name)) return; // referenced by a live producer — never touch
+        const p = join(outDir, name);
+        try {
+            const st = await fsPromises.stat(p);
+            if (st.mtimeMs < cutoff) { await fsPromises.unlink(p).catch(() => {}); return; }
+            if (st.size <= SHELL_JOB_SPILL_MAX_BYTES) return;
+            const buf = await fsPromises.readFile(p);
+            await fsPromises.writeFile(p, buf.subarray(Math.max(0, buf.length - SHELL_JOB_SPILL_KEEP_BYTES)));
+        } catch {}
+    }));
 }
 
 export function getShellJobsDir() {

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

@@ -102,7 +102,19 @@ export function _installShellJobsExitHook() {
     _shellJobsExitHookInstalled = true;
     _ensureProcessListenerHeadroom(['exit', 'SIGTERM', 'SIGINT', 'SIGHUP'], 1);
     try { process.on('exit', _sweepLiveJobsSync); } catch { /* ignore */ }
-    try { process.on('SIGTERM', _sweepLiveJobsSync); } catch { /* ignore */ }
-    try { process.on('SIGINT', _sweepLiveJobsSync); } catch { /* ignore */ }
-    try { process.on('SIGHUP', _sweepLiveJobsSync); } catch { /* ignore */ }
+    // For terminating signals, sweep then restore default POSIX termination
+    // only when we are the last handler. A sweep-only handler swallows the
+    // signal and keeps the process alive; when several such handlers coexist,
+    // each removes itself and the last one to run re-raises so the default
+    // action takes effect without preempting graceful-shutdown listeners.
+    for (const sig of ['SIGTERM', 'SIGINT', 'SIGHUP']) {
+        const onSignal = () => {
+            _sweepLiveJobsSync();
+            try { process.removeListener(sig, onSignal); } catch { /* ignore */ }
+            try {
+                if (process.listenerCount(sig) === 0) process.kill(process.pid, sig);
+            } catch { /* ignore */ }
+        };
+        try { process.on(sig, onSignal); } catch { /* ignore */ }
+    }
 }

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

@@ -27,6 +27,7 @@ import {
     shellJobDonePath,
     shellJobEnforcedPath,
     resolveJobOwnerHostPid,
+    trimShellJobSpill,
     writeShellJobDetail,
     readShellJobDetail,
 } from './shell-job-paths.mjs';
@@ -309,6 +310,7 @@ export function killShellJob(jobId) {
     detail.exitCode = 137;
     detail.error = 'killed by user (KillShell)';
     detail.finishedAt = new Date().toISOString();
+    trimShellJobSpill(detail);
     writeShellJobDetail(detail);
     _unregisterLiveJobPid(detail.pid);
     return { ...attachJobInsights(detail), killed: true };
@@ -340,6 +342,9 @@ function refreshShellJob(jobId) {
         detail.status = exitCode === 0 ? 'completed' : 'failed';
         detail.exitCode = exitCode;
         detail.finishedAt = finishedAt;
+        // Job finished: cap its spill to a bounded tail so a flooding
+        // producer can't leave a 100MB stdout/stderr log behind.
+        trimShellJobSpill(detail);
         writeShellJobDetail(detail);
         _unregisterLiveJobPid(detail.pid);
         return detail;
@@ -352,6 +357,7 @@ function refreshShellJob(jobId) {
         detail.exitCode = 124;
         detail.finishedAt = new Date().toISOString();
         detail.error = `timed out after ${timeoutMs} ms`;
+        trimShellJobSpill(detail);
         writeShellJobDetail(detail);
         _unregisterLiveJobPid(detail.pid);
         return detail;
@@ -365,6 +371,7 @@ function refreshShellJob(jobId) {
         detail.exitCode = 137;
         detail.finishedAt = new Date().toISOString();
         detail.error = `output exceeded ${SHELL_JOB_OUTPUT_DISK_CAP} byte cap`;
+        trimShellJobSpill(detail);
         writeShellJobDetail(detail);
         _unregisterLiveJobPid(detail.pid);
         return detail;

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

@@ -193,9 +193,31 @@ function firstExistingPathFromWhereExcluding(commandName, excludeRe) {
     }
 }
 
+// Kind-aware shell resolution. kind:
+//
+// Resolve a real bash on macOS/Linux. When 'bash' is explicitly requested we
+// must NOT hand back /bin/sh, which on dash/ash distros is not bash and breaks
+// bash-only syntax. Probe common install paths, then `bash` on PATH; only when
+// nothing is found do we fall back to /bin/sh so a shell is still returned.
+function resolvePosixBash() {
+    for (const p of ['/bin/bash', '/usr/bin/bash', '/usr/local/bin/bash', '/opt/homebrew/bin/bash']) {
+        if (existsSync(p)) return shellSpec(p, 'posix');
+    }
+    try {
+        const r = spawnSync('which', ['bash'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 1000 });
+        if (r.status === 0 && r.stdout) {
+            const p = r.stdout.toString('utf8').split(/\r?\n/).map(s => s.trim()).find(Boolean);
+            if (p && existsSync(p)) return shellSpec(p, 'posix');
+        }
+    } catch { /* fall through to /bin/sh */ }
+    return shellSpec('/bin/sh', 'posix');
+}
+
 // Kind-aware shell resolution. kind:
 //  'default'    → identical to resolveShell() (PowerShell on Windows, /bin/sh elsewhere).
-//  'bash'       → on Windows, Git Bash (or null if not installed); elsewhere /bin/sh (POSIX is already bash-compatible).
+//  'bash'       → on Windows, Git Bash (or null if not installed); elsewhere a real bash
+//                 binary (/bin/bash, /usr/bin/bash, or `bash` on PATH), falling back to
+//                 /bin/sh only when no bash exists (dash/ash distros break on bash syntax).
 //  'powershell' → on Windows, resolveShell(); elsewhere pwsh if present, else null.
 // Each kind is memoized independently, but ONLY on success: a resolution miss
 // (null) is not cached, so the caller's clear-error path is re-probed on the
@@ -206,7 +228,7 @@ export function resolveShellFor(kind = 'default') {
 
     let spec = null;
     if (kind === 'bash') {
-        spec = _isWindows() ? resolveWindowsGitBash() : shellSpec('/bin/sh', 'posix');
+        spec = _isWindows() ? resolveWindowsGitBash() : resolvePosixBash();
     } else if (kind === 'powershell') {
         if (_isWindows()) {
             spec = resolveShell();

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

@@ -297,6 +297,7 @@ const EXTERNAL_TOOL_REDIRECTS = new Map([
     ['codebase_search', 'use the `grep` or `code_graph` tool'],
     ['semanticsearch', 'use the `grep` or `code_graph` tool'],
     ['semantic_search', 'use the `grep` or `code_graph` tool'],
+    ['explore', 'not available in this role — use `grep` or `code_graph` for repo search'],
 ]);
 
 export function canonicalizeBuiltinToolName(name) {
@@ -520,7 +521,22 @@ export async function executeBuiltinTool(name, args, cwd, options = {}) {
     }
     })();
     const _withNudge = _maybeAppendGrepSweepNudge(toolName, args, _toolResult, readStateScope);
-    return capToolOutput(_withNudge, options);
+    return capToolOutput(_appendClampNotices(args, _withNudge), options);
+}
+
+// Surface arg-guard clamp notices (args._clampNotices, see pushClampNotice in
+// arg-guard.mjs) on the result text so the caller learns its request was
+// capped. Delete to consume: prevents double-append when a child-builtin
+// result is embedded in the parent's, and leaves no `_clampNotices` residue
+// on the recorded tool-call args in the transcript.
+function _appendClampNotices(args, result) {
+    let notices = null;
+    if (args && Array.isArray(args._clampNotices)) {
+        notices = args._clampNotices;
+        delete args._clampNotices;
+    }
+    if (!notices || notices.length === 0 || typeof result !== 'string') return result;
+    return `${result}\n\n${notices.map((n) => `[arg-guard] ${n}`).join('\n')}`;
 }
 /**
  * Check if a tool name is a builtin tool.

package/src/runtime/agent/orchestrator/tools/code-graph/dispatch.mjs

@@ -51,6 +51,36 @@ function _collectGraphSymbolList(args) {
 
 const CODE_GRAPH_FILE_BATCH_CAP = 20;
 
+// 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 (missing) path.
+function _parseJsonArrayString(v) {
+  if (typeof v !== 'string') return null;
+  const t = v.trim();
+  if (!t.startsWith('[') || !t.endsWith(']')) return null;
+  try {
+    const parsed = JSON.parse(t);
+    if (Array.isArray(parsed)) return parsed.map((x) => String(x || '').trim()).filter(Boolean);
+  } catch { /* not JSON — leave untouched */ }
+  return null;
+}
+
+function _normalizeGraphFileArgs(args) {
+  if (!args || typeof args !== 'object') return args;
+  const fileArr = _parseJsonArrayString(args.file);
+  const filesArr = _parseJsonArrayString(args.files);
+  if (!fileArr && !filesArr) return args;
+  const out = { ...args };
+  if (fileArr) { out.files = Array.isArray(out.files) ? [...fileArr, ...out.files] : fileArr; delete out.file; }
+  if (filesArr) out.files = filesArr;
+  // Collapse a lone entry back to the single-file field for the fast path.
+  if (Array.isArray(out.files) && out.files.length === 1 && !out.file) {
+    out.file = out.files[0];
+    delete out.files;
+  }
+  return out;
+}
+
 function _collectGraphFileList(args) {
   const split = (s) => String(s || '').split(/,+/).map((t) => t.trim()).filter(Boolean);
   const list = [...new Set([
@@ -70,6 +100,13 @@ async function codeGraph(args, cwd, signal = null, options = {}) {
   let mode = String(args?.mode || '').trim();
   if (!mode) throw new Error('code_graph: "mode" is required');
   if (mode === 'search') mode = 'symbol_search';
+  // Name-only "symbols" calls (symbols[]/symbol without a file) are symbol
+  // lookups, not a file outline — absorb into symbol_search instead of
+  // erroring "file not found in graph: (missing file)".
+  if (mode === 'symbols' && !String(args?.file || '').trim()
+      && ((Array.isArray(args?.symbols) && args.symbols.length) || String(args?.symbol || '').trim())) {
+    mode = 'symbol_search';
+  }
 
   if (mode === 'prewarm') {
     const _splitMulti = (s) => String(s || '').split(/[,\s]+/).map((t) => t.trim()).filter(Boolean);
@@ -436,6 +473,7 @@ export async function resolveSymbolReadSpan(cwd, { symbol, path = null, language
 
 export async function executeCodeGraphTool(name, args, cwd, signal = null, options = {}) {
   if (!cwd) throw new Error('find_symbol/code_graph requires cwd — caller did not provide a working directory');
+  args = _normalizeGraphFileArgs(args);
   const fileArg = (args && typeof args.file === 'string' && args.file.trim()) ? args.file.trim() : '';
   const baseCwd = (args && typeof args.cwd === 'string' && args.cwd.trim()) ? args.cwd.trim() : cwd;
   let effectiveCwd = baseCwd;

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,13 +3,13 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Repo-local code structure/flow lookup, not web: symbols/references/calls/deps before text grep. Multiple targets = ONE call with symbols[]/files[], never parallel single-target calls.',
+    description: 'Repo-local code structure/flow lookup (not web): symbols/references/calls/deps. Batch targets as symbols[]/files[] in one call.',
     inputSchema: {
       type: 'object',
       properties: {
-        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers'], description: 'Repo-local operation; code flow before text search.' },
-        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Source file(s): string or array; one call fans out per file (imports/dependents/related/impact/symbols/overview). `file` singular alias also accepted.' },
-        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Identifier(s)/keyword(s): string or array; batch in one call. One anchor is enough. `symbol` singular alias also accepted.' },
+        mode: { type: 'string', enum: ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers'], description: 'Repo-local graph operation.' },
+        files: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Source file(s); array fans out per file. `file` alias too.' },
+        symbols: { anyOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' }, minItems: 1 }], description: 'Identifier(s)/keyword(s); array batches in one call. `symbol` alias too.' },
         symbol: { type: 'string', description: 'Singular alias for symbols.' },
         file: { type: 'string', description: 'Singular alias for files.' },
         body: { type: 'boolean', description: 'Include body.' },

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

@@ -11,7 +11,7 @@ import { withBuiltinPathLocks } from '../builtin.mjs';
 import { withAdvisoryLocks } from '../builtin/advisory-lock.mjs';
 import { wrapMutationRouteOutput } from '../mutation-planner.mjs';
 import { getPluginData } from '../../config.mjs';
-import { prepareInput, isV4APatchInput, hasUnifiedBareV4AHunk, canFallbackCountedUnified, parseV4APatch, isCompactedPlaceholderPatch } from './parsing.mjs';
+import { prepareInput, isV4APatchInput, hasUnifiedBareV4AHunk, canFallbackCountedUnified, parseV4APatch, isCompactedPlaceholderPatch, salvageV4AOpening } from './parsing.mjs';
 import {
   resolveBasePath,
   resolveV4AEntryPath,
@@ -105,7 +105,7 @@ function salvageShatteredV4APatchArgs(args) {
 
 async function apply_patch(args, cwd, options = {}) {
   args = salvageShatteredV4APatchArgs(args);
-  const patchStr = (typeof args?.patch === 'string' ? args.patch : '').replace(/^\uFEFF/, '');
+  const patchStr = salvageV4AOpening((typeof args?.patch === 'string' ? args.patch : '').replace(/^\uFEFF/, ''));
   if (!patchStr.trim()) {
     throw new Error('apply_patch: "patch" is required (unified diff or V4A patch string)');
   }