mixdog 0.9.14 → 0.9.16

package/src/runtime/agent/orchestrator/session/manager/context-meta.mjs

@@ -2,7 +2,8 @@
 // resolution. Extracted verbatim from manager.mjs (behavior-preserving).
 import { getModelMetadataSync } from '../../providers/model-catalog.mjs';
 import { resolveCompactTriggerTokens } from '../context-utils.mjs';
-import { normalizeCompactType, DEFAULT_COMPACT_TYPE } from '../compact.mjs';
+import { COMPACT_TYPE_SEMANTIC, COMPACT_TYPE_RECALL_FASTTRACK, CONTEXT_SHARE_RATIO } from '../compact.mjs';
+import { isAgentOwner } from '../../agent-owner.mjs';
 
 // Known context windows for the current-generation models this plugin
 // routes to. Anything not listed falls through to guessContextWindow() —
@@ -88,9 +89,8 @@ export function preserveBufferConfigFields(cfg = {}) {
     }
     return out;
 }
-const COMPACT_TARGET_RATIO = 0.02;
+const COMPACT_TARGET_RATIO = CONTEXT_SHARE_RATIO;
 const COMPACT_TARGET_MIN_TOKENS = 4_000;
-const COMPACT_TARGET_MAX_TOKENS = 16_000;
 function compactTargetRatio() {
     const raw = process.env.MIXDOG_AGENT_COMPACT_TARGET_PERCENT
         ?? process.env.MIXDOG_COMPACT_TARGET_PERCENT
@@ -108,9 +108,8 @@ function compactTargetTokensForBoundary(boundaryTokens) {
     );
     if (explicit) return Math.max(1, Math.min(boundary, explicit));
     const minTarget = Math.min(boundary, positiveContextWindow(process.env.MIXDOG_COMPACT_TARGET_MIN_TOKENS) || COMPACT_TARGET_MIN_TOKENS);
-    const maxTarget = Math.min(boundary, positiveContextWindow(process.env.MIXDOG_COMPACT_TARGET_MAX_TOKENS) || COMPACT_TARGET_MAX_TOKENS);
     const byRatio = Math.max(1, Math.floor(boundary * compactTargetRatio()));
-    return Math.max(1, Math.min(boundary, maxTarget, Math.max(minTarget, byRatio)));
+    return Math.max(1, Math.min(boundary, Math.max(minTarget, byRatio)));
 }
 function defaultEffectiveContextWindowPercent(provider) {
     // Gateway/statusline route metadata reserves a universal 10% headroom from
@@ -211,20 +210,16 @@ export function compactTargetBudget(boundaryTokens, reserveTokens, _sourceTokens
     const targetEffective = compactTargetTokensForBoundary(boundary) || boundary;
     return Math.max(1, Math.min(boundary, targetEffective + reserve));
 }
-export function semanticCompactionEnabledForSession(session) {
-    const cfg = session?.compaction || {};
-    if (process.env.MIXDOG_AGENT_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_AGENT_COMPACT_SEMANTIC', true);
-    if (process.env.MIXDOG_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_COMPACT_SEMANTIC', true);
-    if (cfg.semantic === false || cfg.semantic === 'false' || cfg.semantic === 'off') return false;
-    if (cfg.semantic === true || cfg.semantic === 'true' || cfg.semantic === 'on' || cfg.semantic === 'auto') return true;
+export function semanticCompactionEnabledForSession(_session) {
+    // Compact types are hard-locked (agent=semantic, main=recall-fasttrack),
+    // so semantic must always be available: it is the agent path AND the
+    // degraded fallback when recall-fasttrack fails. Env/config off-switches
+    // no longer apply.
     return true;
 }
 export function compactTypeForSession(session) {
-    const cfg = session?.compaction || {};
-    const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
-        ?? process.env.MIXDOG_COMPACT_TYPE
-        ?? cfg.type
-        ?? cfg.compactType
-        ?? cfg.compact_type;
-    return normalizeCompactType(configured, DEFAULT_COMPACT_TYPE);
+    // Hard-locked: agent-owned sessions are always semantic, all other
+    // (main/user) sessions are always recall-fasttrack. Env/config overrides
+    // no longer change the type.
+    return isAgentOwner(session) ? COMPACT_TYPE_SEMANTIC : COMPACT_TYPE_RECALL_FASTTRACK;
 }

package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs

@@ -316,7 +316,11 @@ export function drainPendingMessages(sessionId) {
     const q = _sessionPendingMessages.get(sessionId);
     const memory = q && q.length > 0 ? q.slice() : [];
     _sessionPendingMessages.delete(sessionId);
-    const persisted = [...takeBufferedPendingMessages(sessionId), ...drainPersistedPendingMessages(sessionId)];
+    // FIFO: disk-persisted entries were flushed before the not-yet-flushed
+    // in-memory persist buffer, so they are strictly older — drain them
+    // first. Reversing this order (buffer before disk) delivered newer
+    // buffered sends ahead of older persisted ones after a restart.
+    const persisted = [...drainPersistedPendingMessages(sessionId), ...takeBufferedPendingMessages(sessionId)];
     const memoryVisible = modelVisiblePendingMessages(memory);
     const persistedVisible = modelVisiblePendingMessages(persisted);
     if (memoryVisible.length === 0) return persistedVisible;

package/src/runtime/agent/orchestrator/session/manager/tool-resolution.mjs

@@ -87,6 +87,10 @@ function stringToolPermissionAllowList(toolPermission) {
     return null;
 }
 
+// Read-write agent bundle: edit surface (apply_patch) WITHOUT shell/task.
+// Repo-local shell work (git/build/test/verification) is Lead-owned by
+// workflow contract; write-role agents patch files and hand verification
+// back. Only permission 'full' (no narrowing) retains shell.
 const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'code_graph',
     'find',
@@ -95,7 +99,6 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'grep',
     'read',
     'apply_patch',
-    'shell',
     'explore',
     'search',
     'web_fetch',

package/src/runtime/agent/orchestrator/session/manager.mjs

@@ -645,8 +645,12 @@ export function createSession(opts) {
     const agentRulesAgent = opts.agent || opts.role || profile?.taskType || null;
     const agentRulesProfile = isRetrievalAgent ? 'retrieval' : 'full';
     const skipAgentRules = opts.skipAgentRules === true;
-    // Retrieval roles already inject a compact # Tool Use via BP2; skip the full BP1 shared tool policy to avoid duplicating it.
-    const injectedRules = (skipAgentRules || isRetrievalAgent) ? '' : _buildSharedRules();
+    // BP1 shared tool policy ships to EVERY role (Lead, workers, retrieval,
+    // maintenance): its anti-spiral clauses (one anchor is enough, never
+    // repeat equivalent patterns/scopes, plausible hit → stop) are exactly
+    // what narrow retrieval roles need. Role docs (e.g. 30-explorer.md)
+    // override role-inapplicable entries such as the explore routing row.
+    const injectedRules = skipAgentRules ? '' : _buildSharedRules();
     const roleRules = skipAgentRules ? '' : (ownerIsAgent ? _buildAgentRules(agentRulesProfile) : _buildLeadRules());
     const metaContext = skipAgentRules ? '' : (ownerIsAgent ? '' : _buildLeadMetaContext());
     const roleSpecific = ownerIsAgent && !skipAgentRules ? _buildAgentSpecific(agentRulesAgent) : '';
@@ -1918,6 +1922,59 @@ export async function clearSessionMessages(sessionId, options = {}) {
     const beforeTokens = estimateTranscriptContextUsage(messages, session.tools || []);
     const afterTokens = estimateTranscriptContextUsage(keep, session.tools || []);
     const now = Date.now();
+    // --- Fork the outgoing transcript to a separate resumable session BEFORE
+    // the wipe below. Runs for every clear path (plain /clear, auto-clear,
+    // compact_clear) using the ORIGINAL `messages` (post-compact-gating, i.e.
+    // whatever survived the requireCompactSuccess throw above), so the
+    // conversation about to be discarded stays reachable via /resume under a
+    // fresh id. Skipped for scratch sessions with no real user turn — nothing
+    // worth resuming. Best-effort: any failure here must never block the
+    // clear itself (mirrors the pre-compact failure handling above).
+    if (hasUserConversationMessage(messages)) {
+        try {
+            const forkId = `sess_${process.pid}_${nextId++}_${Date.now()}_${randomBytes(16).toString('hex')}`;
+            const fork = {
+                ...session,
+                id: forkId,
+                messages: messages.map((m) => (m && typeof m === 'object' ? { ...m } : m)),
+                closed: false,
+                status: 'idle',
+                generation: 0,
+                createdAt: now,
+                updatedAt: now,
+                lastUsedAt: now,
+                lastHeartbeatAt: null,
+                mcpPid: process.pid,
+                // Strip runtime/liveness/routing state — the fork is a cold
+                // snapshot, not a live process-owned session.
+                clientHostPid: null,
+                providerState: undefined,
+                totalInputTokens: 0,
+                totalOutputTokens: 0,
+                totalCachedReadTokens: 0,
+                totalCacheWriteTokens: 0,
+                lastInputTokens: 0,
+                lastOutputTokens: 0,
+                lastCachedReadTokens: 0,
+                lastCacheWriteTokens: 0,
+                lastContextTokens: 0,
+                lastContextTokensUpdatedAt: now,
+                lastContextTokensStaleAfterCompact: false,
+                // Shell state must not alias the live session: resuming the
+                // fork would otherwise reuse/close the original session's
+                // persistent bash shells.
+                implicitBashSessionId: null,
+                allBashSessionIds: undefined,
+            };
+            delete fork.liveTurnMessages;
+            setLiveSession(fork);
+            void saveSessionAsync(fork).catch((err) => {
+                try { process.stderr.write(`[session] clear-fork save failed (sess=${forkId}): ${err?.message || err}\n`); } catch { /* best-effort */ }
+            });
+        } catch (err) {
+            try { process.stderr.write(`[session] clear-fork failed (sess=${sessionId}): ${err?.message || err}\n`); } catch { /* best-effort */ }
+        }
+    }
     session.messages = keep;
     session.sessionStartMetaInjected = false;
     session.totalInputTokens = 0;

package/src/runtime/agent/orchestrator/session/store-summary-index.mjs

@@ -187,3 +187,21 @@ export function _removeSessionSummary(id) {
         }, { compact: true, lock: true });
     } catch { /* summary index is best-effort */ }
 }
+
+/**
+ * Batch removal: prune MANY ids from the summary index in a single
+ * read-modify-write. Bulk deleters (tombstone sweep) must use this instead
+ * of per-id _removeSessionSummary — the index is O(sessions) in size, so
+ * per-id rewrites make a large sweep quadratic in total I/O.
+ */
+export function _pruneSummaryIndexIds(ids) {
+    if (!(ids instanceof Set) || ids.size === 0) return;
+    try {
+        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
+            const index = _normalizeSummaryIndex(cur);
+            const rows = index.rows.filter((r) => !ids.has(r.id));
+            if (rows.length === index.rows.length) return undefined;
+            return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
+        }, { compact: true, lock: true });
+    } catch { /* summary index is best-effort */ }
+}

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -12,6 +12,7 @@ import { getPluginData } from '../config.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
 import { renameWithRetrySync } from '../../../shared/atomic-file.mjs';
 import { sanitizeContentForStoredHistory } from '../providers/media-normalization.mjs';
+import { scanTopLevelLifecycle } from './lifecycle-scan.mjs';
 import {
     summaryIndexPath,
     _sessionSummary,
@@ -19,6 +20,7 @@ import {
     _writeSummaryIndex,
     _upsertSessionSummary,
     _removeSessionSummary,
+    _pruneSummaryIndexIds,
 } from './store-summary-index.mjs';
 // Facade re-export: summary-index API moved to store-summary-index.mjs; keep
 // prior importers of store.mjs unchanged.
@@ -358,28 +360,21 @@ function _shouldDrop(id, opts) {
     if (!existsSync(target)) return false;
     try {
         const raw = readFileSync(target, 'utf-8');
-        // Tombstone check only needs `closed` and `generation`. Avoid a full
-        // JSON.parse of the entire session (which can be MBs on long chats and
-        // ran on every save). Fast-path a regex scan; only fall back to a full
-        // parse if the lightweight scan is inconclusive.
-        const closedMatch = /"closed"\s*:\s*(true|false)/.exec(raw);
-        if (closedMatch && closedMatch[1] === 'true') {
-            const genMatch = /"generation"\s*:\s*(-?\d+)/.exec(raw);
-            const diskGen = genMatch ? Number(genMatch[1]) : 0;
-            return diskGen >= expected;
-        }
-        if (closedMatch && closedMatch[1] === 'false') {
-            // Not closed — still check the generation-as-ownership-counter
-            // rule (see full-parse branch below) via the same fast regex
-            // scan, so bumpSessionGeneration()'s detach bump is honoured
-            // without paying for a full JSON.parse on every save.
-            const genMatch = /"generation"\s*:\s*(-?\d+)/.exec(raw);
-            const diskGen = genMatch ? Number(genMatch[1]) : 0;
-            return diskGen > expected;
-        }
-        // No `closed` key found by scan — not a tombstone, so nothing to drop.
-        if (!closedMatch && !/"closed"/.test(raw)) return false;
-        const onDisk = JSON.parse(raw);
+        // Tombstone check only needs top-level `closed`/`generation`. A plain
+        // substring/regex pre-check is unsafe on its own: a message body can
+        // contain literal text like `{"closed":true}` (tool result, pasted
+        // JSON) which would spoof the guard if trusted directly. Instead of
+        // JSON.parse'ing the whole document on every guarded save (expensive:
+        // allocates the entire messages array just to read two scalars),
+        // scanTopLevelLifecycle walks the raw text with bracket-depth +
+        // string-escape awareness and only *interprets* key/value pairs at
+        // depth 1 — nested "closed"/"generation" inside messages are skipped
+        // by depth counting, never parsed, so they cannot be mistaken for the
+        // real top-level fields. Falls back to a full parse only if the scan
+        // reports malformed/truncated JSON (should not happen for files we
+        // wrote ourselves, but stay correct over clever).
+        let onDisk = scanTopLevelLifecycle(raw);
+        if (onDisk === null) onDisk = JSON.parse(raw);
         const diskGen = typeof onDisk.generation === 'number' ? onDisk.generation : 0;
         if (onDisk.closed === true) return diskGen >= expected;
         // Not closed, but `generation` also doubles as an ownership counter:
@@ -590,7 +585,7 @@ export function clearSessionSaveError(id) {
     _lastSaveError.delete(id);
 }
 
-export function deleteSession(id) {
+export function deleteSession(id, options = {}) {
     const path = sessionPath(id);
     let removed = false;
     if (existsSync(path)) {
@@ -601,7 +596,10 @@ export function deleteSession(id) {
         catch { /* fall through to .hb cleanup */ }
     }
     _deleteHeartbeat(id);
-    if (removed) _removeSessionSummary(id);
+    // deferSummaryUpdate: bulk callers (tombstone sweep) remove thousands of
+    // rows — a per-id _removeSessionSummary would parse+rewrite the multi-MB
+    // summary index once PER DELETION. They batch the index update themselves.
+    if (removed && options.deferSummaryUpdate !== true) _removeSessionSummary(id);
     return removed;
 }
 const DEFAULT_SESSION_TTL_MS = 5 * 60 * 1000; // 5 minutes idle — aligned with Anthropic 5m messages tier and OpenAI in-memory cache window
@@ -725,7 +723,7 @@ export function sweepStaleSessions(ttlMs, options = {}) {
                     const age = now - updated;
                     if (Number.isFinite(updated) && age >= tombstoneMaxAgeMs) {
                         try {
-                            if (deleteSession(row.id)) {
+                            if (deleteSession(row.id, { deferSummaryUpdate: true })) {
                                 tombstonesCleaned++;
                                 tombstoneDetails.push({ id: row.id, ageSeconds: Math.floor(age / 1000) });
                                 continue;
@@ -799,5 +797,15 @@ export function sweepStaleSessions(ttlMs, options = {}) {
             }
         }
     } catch { /* dir scan failure — non-fatal */ }
+    // Batched summary-index prune for deferred tombstone deletions: one
+    // read-modify-write for the whole sweep instead of one per deleted id
+    // (the index is multi-MB at scale; per-id rewrites made large sweeps
+    // quadratic and stalled boot for seconds).
+    if (tombstoneDetails.length > 0) {
+        try {
+            const deletedIds = new Set(tombstoneDetails.map((d) => d.id));
+            _pruneSummaryIndexIds(deletedIds);
+        } catch { /* summary index is best-effort */ }
+    }
     return { cleaned, remaining, details, tombstonesCleaned, tombstoneDetails, tombstoneErrors };
 }

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

@@ -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; multiple scopes = ONE call with path[].',
+        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.',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -8,7 +8,7 @@ import {
     normalizeOutputPath,
     resolveAgainstCwd,
 } from './path-utils.mjs';
-import { tryReadFamilyEnoentRedirect } from './search-path-diagnostics.mjs';
+import { buildNotFoundHint, finalizeReadFamilyEnoentTail, tryReadFamilyEnoentRedirect } from './search-path-diagnostics.mjs';
 import { normalizeErrorMessage } from './path-diagnostics.mjs';
 import { isUncPath, isWindowsDevicePath, hasUnsafeWin32Component } from './device-paths.mjs';
 import {
@@ -49,7 +49,9 @@ async function readFamilyPathEnoentOrError(workDir, fullPath, inputPath, args, o
         rerun: (target, opts) => rerunTool({ ...args, path: target }, workDir, opts),
     });
     if (redirected) return redirected;
-    return `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+    const msg = `Error: ${normalizeErrorMessage(err instanceof Error ? err.message : String(err))}`;
+    const hint = buildNotFoundHint(workDir, fullPath, 'List', err?.code);
+    return msg + finalizeReadFamilyEnoentTail(hint, inputPath, err?.code);
 }
 
 function normalizeListHeadLimit(raw, defaultCap) {
@@ -344,8 +346,8 @@ export async function executeTreeTool(args, workDir, options = {}) {
 export async function executeFuzzyFindTool(args, workDir, options = {}) {
     if (Array.isArray(args.query)) {
         const list = [...new Set(args.query.map((q) => (typeof q === 'string' ? q.trim() : '')).filter((q) => q.length > 0))];
-        const capped = list.length > 10;
-        const targets = capped ? list.slice(0, 10) : list;
+        const capped = list.length > 5;
+        const targets = capped ? list.slice(0, 5) : list;
         if (targets.length > 1) {
             const sections = [];
             for (const q of targets) {
@@ -357,7 +359,7 @@ export async function executeFuzzyFindTool(args, workDir, options = {}) {
                 }
                 sections.push(`# find ${q}\n${body}`);
             }
-            if (capped) sections.push(`... [capped at 10 of ${list.length} queries]`);
+            if (capped) sections.push(`... [capped at 5 of ${list.length} queries]`);
             return sections.join('\n\n');
         }
         args.query = targets[0];

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

@@ -111,7 +111,8 @@ export function findBySuffixStrip(searchRoot, fullPath, { maxIterations = 12 } =
             const rel = relative(searchRoot, candidate);
             if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) continue;
             try {
-                if (statSync(candidate).isFile()) {
+                const st = statSync(candidate);
+                if (st.isFile() || st.isDirectory()) {
                     return rel.replace(/\\/g, '/');
                 }
             } catch { /* miss this tail length, keep peeling */ }
@@ -120,6 +121,42 @@ export function findBySuffixStrip(searchRoot, fullPath, { maxIterations = 12 } =
     } catch { return null; }
 }
 
+// Same as findFileByBasename but for directories sharing the missing path's
+// final segment name (e.g. guessed `src/shared` → the real `lib/shared`).
+export function findDirectoryByBasename(searchRoot, fullPath, { limit = 3, maxDirs = 6000 } = {}) {
+    try {
+        if (typeof searchRoot !== 'string' || !searchRoot) return [];
+        const target = basename(fullPath).toLowerCase();
+        if (!target) return [];
+        const matches = [];
+        const queue = [searchRoot];
+        let scanned = 0;
+        while (queue.length && matches.length < limit && scanned < maxDirs) {
+            const dir = queue.shift();
+            scanned++;
+            let entries;
+            try { entries = readdirSync(dir, { withFileTypes: true }); }
+            catch { continue; }
+            for (const ent of entries) {
+                const name = ent.name;
+                if (ent.isDirectory()) {
+                    if (name.toLowerCase() === target) {
+                        const hit = join(dir, name);
+                        const rel = relative(searchRoot, hit);
+                        if (rel && !rel.startsWith('..') && !isAbsolute(rel)) {
+                            matches.push(rel.replace(/\\/g, '/'));
+                            if (matches.length >= limit) break;
+                        }
+                    }
+                    if (name.startsWith('.') || BASENAME_SCAN_SKIP_DIRS.has(name)) continue;
+                    queue.push(join(dir, name));
+                }
+            }
+        }
+        return matches;
+    } catch { return []; }
+}
+
 // Node's native fs errors embed the failing path wrapped in single quotes
 // using OS-native separators ('C:\\Users\\foo\\bar.mjs' on Windows). Without
 // this pass, read error bodies surface backslash paths that

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

@@ -243,6 +243,30 @@ export function coerceShapeFlex(value) {
 // left untouched — JSON reinterpretation only runs after a stat miss.
 export function coerceReadFamilyPathArg(path, workDir = null) {
     if (path === undefined || path === null || path === '') return path;
+    if (typeof path === 'string' && typeof workDir === 'string' && workDir) {
+        const trimmed = path.trim();
+        if (/\s/.test(trimmed)) {
+            let fullPathExists = false;
+            try {
+                statSync(resolveAgainstCwd(normalizeInputPath(trimmed), workDir));
+                fullPathExists = true;
+            } catch { /* split only when the literal path is missing */ }
+            if (!fullPathExists) {
+                const segments = trimmed.split(/\s+/).filter(Boolean).map((s) => normalizeInputPath(s));
+                if (segments.length >= 2) {
+                    const allExist = segments.every((seg) => {
+                        try {
+                            statSync(resolveAgainstCwd(seg, workDir));
+                            return true;
+                        } catch {
+                            return false;
+                        }
+                    });
+                    if (allExist) return segments;
+                }
+            }
+        }
+    }
     if (typeof path === 'string' && typeof workDir === 'string' && workDir) {
         const trimmed = path.trim();
         if (trimmed.startsWith('[') && trimmed.endsWith(']')) {

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

@@ -3,7 +3,7 @@ import * as fsPromises from 'fs/promises';
 import { readFile } from 'fs/promises';
 import { extname } from 'path';
 import { normalizeInputPath } from './path-utils.mjs';
-import { buildNotFoundHint, tryReadFamilyEnoentRedirect } from './search-path-diagnostics.mjs';
+import { buildNotFoundHint, finalizeReadFamilyEnoentTail, tryReadFamilyEnoentRedirect } from './search-path-diagnostics.mjs';
 import { getReadSnapshot } from './read-snapshot-runtime.mjs';
 import { snapshotCoversFullFile, statMatchesSnapshot } from './snapshot-helpers.mjs';
 import { formatBinaryReadPreview } from './binary-file.mjs';
@@ -222,6 +222,7 @@ export async function executeSingleReadTool(args, workDir, readStateScope, optio
         if (!similar) {
             hint = buildNotFoundHint(workDir, fullPath, 'Read', err?.code);
         }
+        hint = finalizeReadFamilyEnoentTail(hint, filePath, err?.code);
         const _rawMsg = err instanceof Error ? err.message : String(err);
         const _safeMsg = normalizeErrorMessage(_rawMsg, workDir);
         return `Error: ${_safeMsg}${hint}`;

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

@@ -161,6 +161,14 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
     // Single turn can touch many files or swap modes without
     // the agent iterating across multiple tool names.
     if (Array.isArray(args.path) && args.path.length > 0 && args.path[0] && typeof args.path[0] === 'object') {
+        // Cap batch fan-out: never error on an oversized array, just
+        // truncate and note it in the final output (mirrors list-tool.mjs
+        // path[] cap pattern).
+        if (args.path.length > 10) {
+            const _origObjLen = args.path.length;
+            args.path = args.path.slice(0, 10);
+            args._batchCapNote = `... [capped at 10 of ${_origObjLen} paths]`;
+        }
         // Per-file batch: each entry carries its own options.
         // Coalesce same-path entries: multiple chunks for the same
         // file are merged into a single wider read (min offset to max
@@ -216,6 +224,11 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
         args.mode = undefined; args.n = undefined; args.offset = undefined; args.limit = undefined; args.full = undefined;
     }
     if (Array.isArray(args.path)) {
+        if (args.path.length > 10) {
+            const _origStrLen = args.path.length;
+            args.path = args.path.slice(0, 10);
+            if (!args._batchCapNote) args._batchCapNote = `... [capped at 10 of ${_origStrLen} paths]`;
+        }
         // Schema is `path: string | string[]` — array entries are
         // strings only. Top-level mode / n / offset / limit / full
         // apply uniformly to every entry in the batch (the only
@@ -398,7 +411,7 @@ export async function executeReadTool(args, workDir, readStateScope, executeChil
             const suffix = match ? ` (truncated ${match[1]}L/${match[2]}KB)` : '';
             return `${path} [${mode}] [${status}]${suffix}\n${r.body}`;
         }).join('\n\n');
-        return `${header}\n\n${body}`;
+        return `${header}\n\n${body}${args._batchCapNote ? `\n\n${args._batchCapNote}` : ''}`;
     }
     // W1 H: device-file / UNC / scope guards must run BEFORE mode
     // dispatches so head/tail/wc internal readers can't bypass the

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

@@ -468,6 +468,8 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
         let seenAfterOffset = 0;
         let stoppedEarly = false;
         let timedOut = false;
+        let capExceeded = false;
+        let bufferBytes = 0;
         /** @type {'timeout' | 'early' | null} */
         let killReason = null;
         let settled = false;
@@ -527,6 +529,14 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
             }
             seenAfterOffset++;
             if (seenAfterOffset <= collectLimit) {
+                bufferBytes += Buffer.byteLength(line);
+                if (bufferBytes > MAX_RG_STDOUT_BYTES) {
+                    // Enforce the same 20MB ceiling runRg uses: a runaway
+                    // producer must not balloon the retained-lines heap.
+                    capExceeded = true;
+                    stopEarly();
+                    return;
+                }
                 lines.push(line);
                 return;
             }
@@ -537,6 +547,13 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
         proc.stdout.on('data', (chunk) => {
             if (stoppedEarly) return;
             buffer += chunk;
+            // Guard against an unbounded single line (no newline): cap the
+            // pending buffer at the same 20MB ceiling and stop early.
+            if (buffer.length > MAX_RG_STDOUT_BYTES) {
+                capExceeded = true;
+                stopEarly();
+                return;
+            }
             let start = 0;
             let idx = buffer.indexOf('\n', start);
             while (!stoppedEarly && idx !== -1) {
@@ -579,7 +596,14 @@ function spawnRgWindowedLines(argsList, execOptions, opts = {}) {
                 return reject(e);
             }
             if (stoppedEarly) {
-                return resolve({ lines, complete: false, totalSeen: seenAfterOffset });
+                return resolve({
+                    lines,
+                    complete: false,
+                    totalSeen: seenAfterOffset,
+                    // Surface the 20MB byte-cap breach so the caller can flag
+                    // truncation, mirroring runRg's stdoutTruncated.
+                    ...(capExceeded ? { partial: true, truncated: true } : {}),
+                });
             }
             if (code === 0 || code === 1) {
                 return resolve({ lines, complete: true, totalSeen: seenAfterOffset });