mixdog 0.9.2 → 0.9.4

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

@@ -0,0 +1,189 @@
+/**
+ * Session summary index: the compact `session-summaries.json` sidecar that
+ * lists every session's lightweight metadata (preview, counts, lifecycle) so
+ * the status aggregator and session listers avoid parsing every full session
+ * file. Extracted from store.mjs verbatim; store.mjs re-exports these so
+ * importers stay unchanged.
+ */
+import { mkdirSync } from 'fs';
+import { join } from 'path';
+import { getPluginData } from '../config.mjs';
+import { updateJsonAtomicSync, writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+
+export const SESSION_SUMMARY_INDEX_VERSION = 1;
+
+export function summaryIndexPath() {
+    const dir = getPluginData();
+    mkdirSync(dir, { recursive: true });
+    return join(dir, 'session-summaries.json');
+}
+
+function _messageText(content) {
+    if (typeof content === 'string') return content;
+    if (Array.isArray(content)) {
+        return content.map((part) => {
+            if (typeof part === 'string') return part;
+            if (part?.type === 'text') return part.text || '';
+            if (typeof part?.text === 'string') return part.text;
+            try { return JSON.stringify(part); } catch { return ''; }
+        }).filter(Boolean).join('\n');
+    }
+    if (content && typeof content === 'object') {
+        if (typeof content.text === 'string') return content.text;
+        try { return JSON.stringify(content); } catch { return ''; }
+    }
+    return '';
+}
+
+export function _cleanPreview(text, max = 240) {
+    const value = String(text || '').replace(/\s+/g, ' ').trim();
+    return value.length > max ? value.slice(0, max).replace(/\s+\S*$/, '').trim() : value;
+}
+
+function _isPreviewNoise(text) {
+    const value = String(text || '').trim();
+    if (!value) return true;
+    if (value.startsWith('<system-reminder>')) return true;
+    if (/^Reference files:/i.test(value)) return true;
+    return false;
+}
+
+function _sessionPreview(session) {
+    const messages = Array.isArray(session?.messages) ? session.messages : [];
+    let first = '';
+    for (const m of messages) {
+        if (m?.role !== 'user') continue;
+        const text = _cleanPreview(_messageText(m.content));
+        if (_isPreviewNoise(text)) continue;
+        if (!first) first = text;
+    }
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const m = messages[i];
+        if (m?.role !== 'user') continue;
+        const text = _cleanPreview(_messageText(m.content));
+        if (_isPreviewNoise(text)) continue;
+        return text || first;
+    }
+    return first;
+}
+
+function _sessionMessageCount(session) {
+    const messages = Array.isArray(session?.messages) ? session.messages : [];
+    let count = 0;
+    for (const m of messages) {
+        if (m && (m.role === 'user' || m.role === 'assistant')) count++;
+    }
+    return count;
+}
+
+function _positiveNumber(value, fallback = 0) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+export function _sessionSummary(session) {
+    if (!session?.id) return null;
+    return {
+        id: String(session.id),
+        updatedAt: _positiveNumber(session.updatedAt, Date.now()),
+        createdAt: _positiveNumber(session.createdAt, 0),
+        lastHeartbeatAt: _positiveNumber(session.lastHeartbeatAt, 0),
+        closed: session.closed === true,
+        status: String(session.status || (session.closed === true ? 'closed' : 'idle')),
+        owner: session.owner || 'user',
+        agent: session.agent || null,
+        sourceType: session.sourceType || null,
+        sourceName: session.sourceName || null,
+        scopeKey: session.scopeKey || null,
+        ownerSessionId: session.ownerSessionId || null,
+        clientHostPid: _positiveNumber(session.clientHostPid, 0) || null,
+        cwd: session.cwd || '',
+        provider: session.provider || null,
+        model: session.model || null,
+        agentTag: session.agentTag || null,
+        task_id: session.task_id || session.taskId || null,
+        permission: session.permission || null,
+        toolPermission: session.toolPermission || null,
+        messageCount: _sessionMessageCount(session),
+        preview: _sessionPreview(session),
+        generation: typeof session.generation === 'number' ? session.generation : 0,
+        implicitBashSessionId: session.implicitBashSessionId || null,
+    };
+}
+
+function _normalizeSummaryRow(row) {
+    if (!row?.id || typeof row.id !== 'string' || !/^[A-Za-z0-9_-]+$/.test(row.id)) return null;
+    return {
+        id: row.id,
+        updatedAt: _positiveNumber(row.updatedAt, 0),
+        createdAt: _positiveNumber(row.createdAt, 0),
+        lastHeartbeatAt: _positiveNumber(row.lastHeartbeatAt, 0),
+        closed: row.closed === true,
+        status: String(row.status || (row.closed === true ? 'closed' : 'idle')),
+        owner: row.owner || 'user',
+        agent: row.agent || null,
+        sourceType: row.sourceType || null,
+        sourceName: row.sourceName || null,
+        scopeKey: row.scopeKey || null,
+        ownerSessionId: row.ownerSessionId || null,
+        clientHostPid: _positiveNumber(row.clientHostPid, 0) || null,
+        cwd: row.cwd || '',
+        provider: row.provider || null,
+        model: row.model || null,
+        agentTag: row.agentTag || null,
+        task_id: row.task_id || null,
+        permission: row.permission || null,
+        toolPermission: row.toolPermission || null,
+        messageCount: Math.max(0, Math.floor(Number(row.messageCount) || 0)),
+        preview: _cleanPreview(row.preview || ''),
+        generation: typeof row.generation === 'number' ? row.generation : 0,
+        implicitBashSessionId: row.implicitBashSessionId || null,
+    };
+}
+
+export function _normalizeSummaryIndex(raw) {
+    const rows = Array.isArray(raw?.rows) ? raw.rows.map(_normalizeSummaryRow).filter(Boolean) : [];
+    rows.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+    return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: _positiveNumber(raw?.updatedAt, 0), rows };
+}
+
+export function _writeSummaryIndex(rows) {
+    const cleanRows = (rows || []).map(_normalizeSummaryRow).filter(Boolean)
+        .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+    writeJsonAtomicSync(summaryIndexPath(), {
+        version: SESSION_SUMMARY_INDEX_VERSION,
+        updatedAt: Date.now(),
+        rows: cleanRows,
+    }, { compact: true, lock: true });
+    return cleanRows;
+}
+
+export function _upsertSessionSummary(session) {
+    const row = _sessionSummary(session);
+    if (!row) return;
+    try {
+        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
+            const index = _normalizeSummaryIndex(cur);
+            const rows = index.rows.filter((r) => r.id !== row.id);
+            const cleanRow = _normalizeSummaryRow(row);
+            if (!cleanRow) return undefined;
+            const existing = index.rows.find((r) => r.id === row.id) || null;
+            if (existing && JSON.stringify(existing) === JSON.stringify(cleanRow)) return undefined;
+            rows.push(cleanRow);
+            rows.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+            return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
+        }, { compact: true, lock: true });
+    } catch { /* summary index is best-effort */ }
+}
+
+export function _removeSessionSummary(id) {
+    if (!id) return;
+    try {
+        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
+            const index = _normalizeSummaryIndex(cur);
+            const rows = index.rows.filter((r) => r.id !== 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

@@ -10,11 +10,29 @@ import { join } from 'path';
 import { Worker } from 'worker_threads';
 import { getPluginData } from '../config.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
-import { renameWithRetrySync, updateJsonAtomicSync, writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+import { renameWithRetrySync } from '../../../shared/atomic-file.mjs';
 import { sanitizeContentForStoredHistory } from '../providers/media-normalization.mjs';
+import {
+    summaryIndexPath,
+    _sessionSummary,
+    _normalizeSummaryIndex,
+    _writeSummaryIndex,
+    _upsertSessionSummary,
+    _removeSessionSummary,
+} from './store-summary-index.mjs';
+// Facade re-export: summary-index API moved to store-summary-index.mjs; keep
+// prior importers of store.mjs unchanged.
+export {
+    SESSION_SUMMARY_INDEX_VERSION,
+    summaryIndexPath,
+    _sessionSummary,
+    _normalizeSummaryIndex,
+    _writeSummaryIndex,
+    _upsertSessionSummary,
+    _removeSessionSummary,
+} from './store-summary-index.mjs';
 
 const _lastSaveError = new Map(); // id -> { message, at }
-const SESSION_SUMMARY_INDEX_VERSION = 1;
 
 // The live in-memory session (and every model request)
 // retains attached image bytes across turns so multi-turn recognition works.
@@ -71,11 +89,6 @@ function sessionPath(id) {
     }
     return join(getStoreDir(), `${id}.json`);
 }
-function summaryIndexPath() {
-    const dir = getPluginData();
-    mkdirSync(dir, { recursive: true });
-    return join(dir, 'session-summaries.json');
-}
 /**
  * Ensure generation/closed defaults on every session object.
  * Older persisted sessions predate these fields; we normalise at load and save.
@@ -88,176 +101,6 @@ function _ensureLifecycleFields(session) {
     return session;
 }
 
-function _messageText(content) {
-    if (typeof content === 'string') return content;
-    if (Array.isArray(content)) {
-        return content.map((part) => {
-            if (typeof part === 'string') return part;
-            if (part?.type === 'text') return part.text || '';
-            if (typeof part?.text === 'string') return part.text;
-            try { return JSON.stringify(part); } catch { return ''; }
-        }).filter(Boolean).join('\n');
-    }
-    if (content && typeof content === 'object') {
-        if (typeof content.text === 'string') return content.text;
-        try { return JSON.stringify(content); } catch { return ''; }
-    }
-    return '';
-}
-
-function _cleanPreview(text, max = 240) {
-    const value = String(text || '').replace(/\s+/g, ' ').trim();
-    return value.length > max ? value.slice(0, max).replace(/\s+\S*$/, '').trim() : value;
-}
-
-function _isPreviewNoise(text) {
-    const value = String(text || '').trim();
-    if (!value) return true;
-    if (value.startsWith('<system-reminder>')) return true;
-    if (/^Reference files:/i.test(value)) return true;
-    return false;
-}
-
-function _sessionPreview(session) {
-    const messages = Array.isArray(session?.messages) ? session.messages : [];
-    let first = '';
-    for (const m of messages) {
-        if (m?.role !== 'user') continue;
-        const text = _cleanPreview(_messageText(m.content));
-        if (_isPreviewNoise(text)) continue;
-        if (!first) first = text;
-    }
-    for (let i = messages.length - 1; i >= 0; i -= 1) {
-        const m = messages[i];
-        if (m?.role !== 'user') continue;
-        const text = _cleanPreview(_messageText(m.content));
-        if (_isPreviewNoise(text)) continue;
-        return text || first;
-    }
-    return first;
-}
-
-function _sessionMessageCount(session) {
-    const messages = Array.isArray(session?.messages) ? session.messages : [];
-    let count = 0;
-    for (const m of messages) {
-        if (m && (m.role === 'user' || m.role === 'assistant')) count++;
-    }
-    return count;
-}
-
-function _positiveNumber(value, fallback = 0) {
-    const n = Number(value);
-    return Number.isFinite(n) && n > 0 ? n : fallback;
-}
-
-function _sessionSummary(session) {
-    if (!session?.id) return null;
-    return {
-        id: String(session.id),
-        updatedAt: _positiveNumber(session.updatedAt, Date.now()),
-        createdAt: _positiveNumber(session.createdAt, 0),
-        lastHeartbeatAt: _positiveNumber(session.lastHeartbeatAt, 0),
-        closed: session.closed === true,
-        status: String(session.status || (session.closed === true ? 'closed' : 'idle')),
-        owner: session.owner || 'user',
-        agent: session.agent || null,
-        sourceType: session.sourceType || null,
-        sourceName: session.sourceName || null,
-        scopeKey: session.scopeKey || null,
-        ownerSessionId: session.ownerSessionId || null,
-        clientHostPid: _positiveNumber(session.clientHostPid, 0) || null,
-        cwd: session.cwd || '',
-        provider: session.provider || null,
-        model: session.model || null,
-        agentTag: session.agentTag || null,
-        task_id: session.task_id || session.taskId || null,
-        permission: session.permission || null,
-        toolPermission: session.toolPermission || null,
-        messageCount: _sessionMessageCount(session),
-        preview: _sessionPreview(session),
-        generation: typeof session.generation === 'number' ? session.generation : 0,
-        implicitBashSessionId: session.implicitBashSessionId || null,
-    };
-}
-
-function _normalizeSummaryRow(row) {
-    if (!row?.id || typeof row.id !== 'string' || !/^[A-Za-z0-9_-]+$/.test(row.id)) return null;
-    return {
-        id: row.id,
-        updatedAt: _positiveNumber(row.updatedAt, 0),
-        createdAt: _positiveNumber(row.createdAt, 0),
-        lastHeartbeatAt: _positiveNumber(row.lastHeartbeatAt, 0),
-        closed: row.closed === true,
-        status: String(row.status || (row.closed === true ? 'closed' : 'idle')),
-        owner: row.owner || 'user',
-        agent: row.agent || null,
-        sourceType: row.sourceType || null,
-        sourceName: row.sourceName || null,
-        scopeKey: row.scopeKey || null,
-        ownerSessionId: row.ownerSessionId || null,
-        clientHostPid: _positiveNumber(row.clientHostPid, 0) || null,
-        cwd: row.cwd || '',
-        provider: row.provider || null,
-        model: row.model || null,
-        agentTag: row.agentTag || null,
-        task_id: row.task_id || null,
-        permission: row.permission || null,
-        toolPermission: row.toolPermission || null,
-        messageCount: Math.max(0, Math.floor(Number(row.messageCount) || 0)),
-        preview: _cleanPreview(row.preview || ''),
-        generation: typeof row.generation === 'number' ? row.generation : 0,
-        implicitBashSessionId: row.implicitBashSessionId || null,
-    };
-}
-
-function _normalizeSummaryIndex(raw) {
-    const rows = Array.isArray(raw?.rows) ? raw.rows.map(_normalizeSummaryRow).filter(Boolean) : [];
-    rows.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-    return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: _positiveNumber(raw?.updatedAt, 0), rows };
-}
-
-function _writeSummaryIndex(rows) {
-    const cleanRows = (rows || []).map(_normalizeSummaryRow).filter(Boolean)
-        .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-    writeJsonAtomicSync(summaryIndexPath(), {
-        version: SESSION_SUMMARY_INDEX_VERSION,
-        updatedAt: Date.now(),
-        rows: cleanRows,
-    }, { compact: true, lock: true });
-    return cleanRows;
-}
-
-function _upsertSessionSummary(session) {
-    const row = _sessionSummary(session);
-    if (!row) return;
-    try {
-        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
-            const index = _normalizeSummaryIndex(cur);
-            const rows = index.rows.filter((r) => r.id !== row.id);
-            const cleanRow = _normalizeSummaryRow(row);
-            if (!cleanRow) return undefined;
-            const existing = index.rows.find((r) => r.id === row.id) || null;
-            if (existing && JSON.stringify(existing) === JSON.stringify(cleanRow)) return undefined;
-            rows.push(cleanRow);
-            rows.sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
-            return { version: SESSION_SUMMARY_INDEX_VERSION, updatedAt: Date.now(), rows };
-        }, { compact: true, lock: true });
-    } catch { /* summary index is best-effort */ }
-}
-
-function _removeSessionSummary(id) {
-    if (!id) return;
-    try {
-        updateJsonAtomicSync(summaryIndexPath(), (cur) => {
-            const index = _normalizeSummaryIndex(cur);
-            const rows = index.rows.filter((r) => r.id !== 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 */ }
-}
-
 /** Module-level map tracking in-flight saves per session ID to prevent concurrent write corruption. */
 const _savePending = new Map();
 
@@ -520,17 +363,34 @@ function _shouldDrop(id, opts) {
         // 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] === 'false') return false;
         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);
         const diskGen = typeof onDisk.generation === 'number' ? onDisk.generation : 0;
-        return onDisk.closed === true && diskGen >= expected;
+        if (onDisk.closed === true) return diskGen >= expected;
+        // Not closed, but `generation` also doubles as an ownership counter:
+        // normal in-place saves (updateSession/appendMessage/etc.) never bump
+        // it, only closeSession()-family calls do (markSessionClosed and its
+        // non-tombstoning sibling bumpSessionGeneration). So if disk
+        // generation is strictly greater than what this write expected,
+        // ownership moved on (session was detached-closed and possibly
+        // resumed) after our turn started — drop the stale write rather than
+        // let it clobber whatever happened after the handoff.
+        return diskGen > expected;
     } catch {
         return false;
     }
@@ -666,6 +526,41 @@ export function markSessionClosed(id, reason = 'manual') {
     return newGen;
 }
 
+/**
+ * Bump a session's generation WITHOUT planting a closed:true tombstone.
+ * Used by closeSession(id, reason, { tombstone: false }) — the runtime side
+ * (heartbeat, bash shells, controller, in-memory entry) is detached, but the
+ * session file itself stays valid/resumable. The generation bump alone is
+ * what protects it from a late save race: any saveSession() still in flight
+ * from the detached turn was issued with the OLD generation as its
+ * `expectedGeneration`, so once we bump the on-disk generation here, that
+ * late write's own _shouldDrop() check (generation-as-ownership-counter
+ * rule, see below) sees disk generation > expected and drops itself instead
+ * of clobbering whatever the resumed session writes next.
+ * Returns the new generation, or null if the session file doesn't exist.
+ */
+export function bumpSessionGeneration(id, reason = 'detach') {
+    _clearDebounce(id);
+    const existing = loadSession(id);
+    if (!existing) return null;
+    const newGen = (typeof existing.generation === 'number' ? existing.generation : 0) + 1;
+    const detached = { ...existing, generation: newGen, updatedAt: Date.now(), detachedReason: reason };
+    const target = sessionPath(id);
+    const tmp = target + '.' + randomBytes(6).toString('hex') + '.tmp';
+    try {
+        writeFileSync(tmp, JSON.stringify(_sessionForDisk(detached)), 'utf-8');
+        _renameWithRetrySync(tmp, target);
+    } catch {
+        try { unlinkSync(tmp); } catch { /* ignore */ }
+        return null;
+    }
+    _savePending.delete(id);
+    _clearLiveSession(id);
+    _deleteHeartbeat(id);
+    _upsertSessionSummary(detached);
+    return newGen;
+}
+
 export function loadSession(id) {
     const path = sessionPath(id);
     // Read-your-writes: if a save is pending (debouncing, scheduled, or queued

package/src/runtime/agent/orchestrator/stall-policy.mjs

@@ -181,9 +181,9 @@ export const PROVIDER_WS_ACQUIRE_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
 );
 
-// Single inter-chunk idle timer, matching codex's DEFAULT_STREAM_IDLE_TIMEOUT_MS
-// (300s). codex resets one idle timer on every received WS frame; mixdog does
-// the same (openai-oauth-ws messageHandler resets on every parsed event). There
+// Single inter-chunk idle timer (300s), matching the upstream WS provider's
+// default stream idle timeout. Mixdog resets one idle timer on every received
+// WS frame (openai-oauth-ws messageHandler resets on every parsed event). There
 // is deliberately no separate "first-meaningful" watchdog — a live stream
 // (including server-side reasoning ACKed via response.created) keeps this timer
 // fresh, and only true socket silence trips it. Env-tunable.

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

@@ -85,7 +85,7 @@ function isStringOrStringArray(v) {
     return true;
 }
 
-function hasUnsupportedRipgrepRegex(value) {
+export function hasUnsupportedRipgrepRegex(value) {
     const values = Array.isArray(value) ? value : [value];
     return values.some((item) => {
         if (typeof item !== 'string') return false;
@@ -99,6 +99,30 @@ function hasMultipleAbsoluteWindowsPaths(value) {
     return Array.isArray(matches) && matches.length > 1;
 }
 
+// Rescue for hasMultipleAbsoluteWindowsPaths: a single string arg that packs
+// multiple absolute Windows paths together (space/comma/semicolon separated,
+// e.g. "C:\a\b C:\c\d" or "C:\a\b, C:\c\d") is a common model mistake meaning
+// two separate search roots, not one malformed path. Split on each drive-
+// letter boundary and trim separator debris instead of hard-erroring;
+// executeGrepTool's own array fan-out (search-tool.mjs) already knows how to
+// run one grep per path and join the results. Returns null when the value
+// does not cleanly resolve to 2+ non-empty segments.
+function splitMultipleAbsoluteWindowsPaths(value) {
+    if (typeof value !== 'string') return null;
+    const starts = [];
+    const re = /[A-Za-z]:[\\/]/g;
+    let m;
+    while ((m = re.exec(value)) !== null) starts.push(m.index);
+    if (starts.length < 2) return null;
+    const parts = [];
+    for (let i = 0; i < starts.length; i++) {
+        const end = i + 1 < starts.length ? starts[i + 1] : value.length;
+        const part = value.slice(starts[i], end).trim().replace(/[,;]+$/, '').trim();
+        if (part) parts.push(part);
+    }
+    return parts.length > 1 ? parts : null;
+}
+
 function hasWindowsDrivePath(value) {
     return typeof value === 'string' && /[A-Za-z]:[\\/]/.test(value);
 }
@@ -124,9 +148,15 @@ function coerceIntegerString(v) {
     return n;
 }
 
+// Range-shaped strings ("1,40", "1-40", "1:40") are a common model mistake
+// when trying to pass a line range through a single-integer field. They are
+// not coerced (ambiguous which bound is intended); instead the rejection
+// tells the model exactly what to do instead.
+const RANGE_SHAPED_INT_STRING = /^\d+\s*[,\-:]\s*\d+$/;
+
 // 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) {
+function checkIntInRange(a, field, min, max, opts = {}) {
     let value = a[field];
     if (value === undefined || value === null) return null;
     if (typeof value === 'string') {
@@ -136,8 +166,20 @@ function checkIntInRange(a, field, min, max) {
             a[field] = coerced;
         }
     }
+    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}")`;
+    }
     if (!isFiniteInt(value)) {
-        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)})`;
+        return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)}); expected a single integer like 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
+    // a shape violation worth a retry turn, just clamp to the boundary.
+    if (opts.clamp) {
+        if (value < min) { a[field] = min; return null; }
+        if (value > max) { a[field] = max; return null; }
+        a[field] = value;
+        return null;
     }
     if (value < min) {
         return `Error: builtin arg "${field}" must be >= ${min} (got ${value})`;
@@ -216,10 +258,11 @@ function guardGrep(a) {
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
-        if (hasOwn(a, k) && hasUnsupportedRipgrepRegex(a[k])) {
-            return `Error: grep arg "${k}" uses regex syntax ripgrep does not support here (lookaround/backrefs). Use plain pattern arrays or simpler regex.`;
-        }
     }
+    // Lookaround/backreference patterns are no longer hard-rejected here:
+    // executeGrepTool (search-tool.mjs) detects them at runtime and routes to
+    // rg's PCRE2 engine (-P/--pcre2) when the installed rg build supports it,
+    // falling back to this same error text only when PCRE2 is unavailable.
     for (const k of globKeys) {
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
@@ -231,7 +274,11 @@ function guardGrep(a) {
             return `Error: grep arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
         if (hasOwn(a, k) && hasMultipleAbsoluteWindowsPaths(a[k])) {
-            return `Error: grep arg "${k}" contains multiple absolute paths in one string. Use one common parent path plus glob, or separate grep calls.`;
+            const split = splitMultipleAbsoluteWindowsPaths(a[k]);
+            if (!split) {
+                return `Error: grep arg "${k}" contains multiple absolute paths in one string. Use one common parent path plus glob, or separate grep calls.`;
+            }
+            a[k] = split;
         }
     }
     for (const k of ['head_limit', 'offset']) {
@@ -239,7 +286,7 @@ function guardGrep(a) {
         if (err) return err;
     }
     for (const k of ['-A', '-B', '-C', 'context']) {
-        const err = checkIntInRange(a, k, 0, GREP_CONTEXT_MAX);
+        const err = checkIntInRange(a, k, 0, GREP_CONTEXT_MAX, { clamp: true });
         if (err) return err;
     }
     // output_mode / mode enum
@@ -291,13 +338,19 @@ function applyLineContextWindow(obj, labelPrefix) {
     if (!hasLine) {
         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}")`;
+    }
     if (!isFiniteInt(obj.line) || obj.line < 1) {
-        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)})`;
+        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)}); expected a single integer like 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}")`;
+        }
         if (!isFiniteInt(obj.context) || obj.context < 0) {
-            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)})`;
+            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)}); expected a single integer like 40`;
         }
         ctx = obj.context;
     }
@@ -381,13 +434,6 @@ function guardRead(a) {
     return null;
 }
 
-function guardDiagnostics(a) {
-    if (hasOwn(a, 'path') && a.path !== undefined && a.path !== null && !isNonEmptyString(a.path)) {
-        return `Error: diagnostics arg "path" must be a non-empty string (got ${describeType(a.path)})`;
-    }
-    return null;
-}
-
 function guardShell(a) {
     if (!hasOwn(a, 'command')) {
         return 'Error: shell requires "command"';
@@ -458,8 +504,13 @@ function guardList(a) {
 }
 
 function guardFind(a) {
-    if (!hasOwn(a, 'query') || typeof a.query !== 'string' || a.query.trim().length === 0) {
-        return `Error: find requires non-empty string "query" (got ${describeType(a.query)})`;
+    // query accepts string or string[] (query[] fans out per-lookup downstream).
+    const queryOk = hasOwn(a, 'query') && (
+        (typeof a.query === 'string' && a.query.trim().length > 0)
+        || (Array.isArray(a.query) && a.query.length > 0 && a.query.every((q) => typeof q === 'string' && q.trim().length > 0))
+    );
+    if (!queryOk) {
+        return `Error: find requires non-empty string (or string[]) "query" (got ${describeType(a.query)})`;
     }
     if (hasOwn(a, 'path') && !isString(a.path)) {
         return `Error: find arg "path" must be a string (got ${describeType(a.path)})`;
@@ -541,7 +592,6 @@ function guardCodeGraph(a) {
 const GUARDS = {
     grep: guardGrep,
     read: guardRead,
-    diagnostics: guardDiagnostics,
     shell: guardShell,
     task: guardTask,
     list: guardList,