mixdog 0.9.0 → 0.9.2

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

@@ -161,7 +161,7 @@ function _sessionSummary(session) {
         closed: session.closed === true,
         status: String(session.status || (session.closed === true ? 'closed' : 'idle')),
         owner: session.owner || 'user',
-        role: session.role || null,
+        agent: session.agent || null,
         sourceType: session.sourceType || null,
         sourceName: session.sourceName || null,
         scopeKey: session.scopeKey || null,
@@ -191,7 +191,7 @@ function _normalizeSummaryRow(row) {
         closed: row.closed === true,
         status: String(row.status || (row.closed === true ? 'closed' : 'idle')),
         owner: row.owner || 'user',
-        role: row.role || null,
+        agent: row.agent || null,
         sourceType: row.sourceType || null,
         sourceName: row.sourceName || null,
         scopeKey: row.scopeKey || null,
@@ -655,11 +655,11 @@ export function markSessionClosed(id, reason = 'manual') {
             const _lifeMs = (typeof existing.createdAt === 'number' && existing.createdAt > 0)
                 ? (tombstone.updatedAt - existing.createdAt)
                 : 0;
-            const _role = existing.role || '-';
+            const _agent = existing.agent || '-';
             const _owner = existing.owner || '-';
             void fsp.appendFile(
                 join(_dataDir, 'tool-events.log'),
-                `[${_ts}] [session-close] owner=${_owner} role=${_role} reason=${reason} lifeMs=${_lifeMs} id=${id}\n`,
+                `[${_ts}] [session-close] owner=${_owner} agent=${_agent} reason=${reason} lifeMs=${_lifeMs} id=${id}\n`,
             ).catch(() => {});
         }
     } catch { /* logger never breaks the close path */ }

package/src/runtime/agent/orchestrator/session/tool-envelope.mjs

@@ -0,0 +1,61 @@
+/**
+ * tool-envelope.mjs — general optional `newMessages` channel for tool results.
+ *
+ * A tool MAY return either:
+ *   - legacy: a string (or existing structured media object) — unchanged, OR
+ *   - an envelope object:
+ *       { __toolEnvelope: true, result: <string|structured>,
+ *         newMessages: [{ role:'user', content:'...' }, ...] }
+ *
+ * The `__toolEnvelope` marker is deliberately namespaced so it can NEVER be
+ * confused with the existing structured media content objects that
+ * PostToolUse hooks/tests preserve (those use `{ content: [...] }`, never
+ * `__toolEnvelope`). `normalizeToolEnvelope` is the single split point: it
+ * returns `{ result, newMessages }` so ALL downstream loop code sees only
+ * `result` and the loop alone is responsible for flushing `newMessages`.
+ */
+
+export const TOOL_ENVELOPE_MARKER = '__toolEnvelope';
+
+export function isToolEnvelope(value) {
+    return !!value
+        && typeof value === 'object'
+        && !Array.isArray(value)
+        && value[TOOL_ENVELOPE_MARKER] === true;
+}
+
+function isValidNewMessage(m) {
+    return !!m
+        && typeof m === 'object'
+        && m.role === 'user'
+        && typeof m.content === 'string'
+        && m.content.length > 0;
+}
+
+/**
+ * Build a tool-result envelope. `result` is the short stub/data the model
+ * sees as the tool_result; `newMessages` are appended (as their own
+ * messages, e.g. role:'user') AFTER the batch's tool results.
+ */
+export function makeToolEnvelope(result, newMessages = []) {
+    return {
+        [TOOL_ENVELOPE_MARKER]: true,
+        result,
+        newMessages: Array.isArray(newMessages) ? newMessages.filter(isValidNewMessage) : [],
+    };
+}
+
+/**
+ * Split a tool return value into `{ result, newMessages }`.
+ *   - legacy string/object → { result: value, newMessages: [] }
+ *   - envelope             → { result, newMessages } (newMessages validated)
+ */
+export function normalizeToolEnvelope(value) {
+    if (isToolEnvelope(value)) {
+        const newMessages = Array.isArray(value.newMessages)
+            ? value.newMessages.filter(isValidNewMessage)
+            : [];
+        return { result: value.result, newMessages };
+    }
+    return { result: value, newMessages: [] };
+}

package/src/runtime/agent/orchestrator/session/tool-result-offload.mjs

@@ -21,11 +21,16 @@ export const TOOL_RESULT_OFFLOAD_PREFIX = '[tool output offloaded:';
 // READ_MAX_SIZE_BYTES cap, so persisting to a sidecar to be re-read would be
 // circular. These values keep context-rich IO tools from turning into "read
 // saved output" loops while bounding the per-call inline footprint per CC.
+// Skill / skill_view bodies stay inline for the same reason — offloading a
+// loaded SKILL.md would force a read loop and defeat the loaded-skill guard.
 const INLINE_THRESHOLD_BY_TOOL = new Map([
     ['read', Infinity],
     ['head', Infinity],
     ['tail', Infinity],
     ['diff', Infinity],
+    ['skill', Infinity],
+    ['skill_view', Infinity],
+    ['skills_list', Infinity],
     ['grep', TOOL_RESULT_GREP_THRESHOLD_CHARS],
     ['glob', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
     ['list', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],

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

@@ -1,4 +1,4 @@
-import { getHiddenRole } from './internal-roles.mjs';
+import { getHiddenAgent } from './internal-agents.mjs';
 
 const SECOND_MS = 1000;
 const MIN_PROVIDER_TIMEOUT_MS = 30_000;
@@ -68,7 +68,13 @@ export const DEFAULT_ACTIVITY_HEARTBEAT_MS = resolveTimeoutMs(
 
 export const PROVIDER_FIRST_BYTE_TIMEOUT_MS = resolveTimeoutMs(
     'MIXDOG_PROVIDER_FIRST_BYTE_TIMEOUT_MS',
-    Math.min(120_000, PROVIDER_MAX_BEFORE_WARN_MS),
+    // 2026-07 trace audit: heavy-worker claude-sonnet-5 xhigh TTFT distribution
+    // showed avg ~25s, max ~120s (15/75 requests over 60s) — the old 120s
+    // window sat exactly on the observed tail and killed/retried healthy slow
+    // first bytes (9 first-byte retries in one 75-iteration session, plus one
+    // full turn lost). 180s clears the tail while the mid-stream retry ladder
+    // and the agent stall watchdog still bound a truly dead socket.
+    Math.min(180_000, PROVIDER_MAX_BEFORE_WARN_MS),
     { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
 );
 
@@ -125,6 +131,44 @@ export const PROVIDER_SSE_IDLE_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: 10_000, maxMs: STALL_WARN_MS },
 );
 
+// Semantic (last-meaningful-event) idle window. Distinct name from the
+// transport-byte SSE idle so provider loops can key their mid-stream abort off
+// SEMANTIC progress (message/content/tool deltas) rather than raw keepalive
+// bytes (Anthropic `:ping`, comment frames). A truly silent stream — one that
+// emits no semantic event for this window — trips it; a live extended-thinking
+// stream (which emits thinking deltas) stays alive. Default 120s, floor 10s,
+// env-overridable and disablable via MIXDOG_ENABLE_STREAM_WATCHDOG=0.
+export const PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS = resolveTimeoutMs(
+    ['MIXDOG_PROVIDER_SEMANTIC_IDLE_TIMEOUT_MS', 'MIXDOG_PROVIDER_SSE_IDLE_TIMEOUT_MS'],
+    // Raised 120s→180s alongside PROVIDER_FIRST_BYTE_TIMEOUT_MS (see comment
+    // there): observed healthy inter-event gaps on xhigh reasoning streams
+    // brushed the old 120s window; stalls after a tool emit are unretryable,
+    // so a false trip there costs the whole turn.
+    180_000,
+    { minMs: 10_000, maxMs: STALL_WARN_MS },
+);
+
+// Named terminal error for a mid-stream SEMANTIC idle abort. Distinct from a
+// user cancel (signal.aborted): the retry-classifier treats this as a terminal
+// STREAM FAILURE so the owner (Lead) receives a failure notification instead of
+// the task hanging. The message keeps "timed out after …ms of inactivity" so
+// the SSE mid-stream classifier's text match (sse_idle_timeout) still fires,
+// and code 'ESTREAMSTALL' routes it through the transient/notify path.
+export function streamStalledError(label, timeoutMs, { emittedToolCall = false } = {}) {
+    const err = new Error(`${label} stream timed out after ${timeoutMs}ms of inactivity`);
+    err.name = 'StreamStalledError';
+    err.code = 'ESTREAMSTALL';
+    err.streamStalled = true;
+    // Double-dispatch guard (reviewer High): once a tool call has already been
+    // emitted this turn (including a recovered text-leaked call), retrying the
+    // request would RE-RUN that side-effecting tool. Mark such a stall
+    // unsafe-to-retry so withRetry() throws it straight through to the terminal
+    // notify path instead of replaying the turn. A stall BEFORE any tool emit is
+    // still safely retryable (nothing has executed yet).
+    if (emittedToolCall) err.unsafeToRetry = true;
+    return err;
+}
+
 export const PROVIDER_WS_HANDSHAKE_TIMEOUT_MS = resolveTimeoutMs(
     'MIXDOG_PROVIDER_WS_HANDSHAKE_TIMEOUT_MS',
     30_000,
@@ -137,19 +181,23 @@ export const PROVIDER_WS_ACQUIRE_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
 );
 
-export const PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS = resolveTimeoutMs(
-    'MIXDOG_PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS',
-    Math.min(PROVIDER_FIRST_BYTE_TIMEOUT_MS, PROVIDER_GENERATE_TOTAL_TIMEOUT_MS),
-    { minMs: MIN_PROVIDER_TIMEOUT_MS, 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
+// 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.
 export const PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS = resolveTimeoutMs(
     'MIXDOG_PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS',
-    STALL_ABORT_MS,
-    { minMs: STALL_WARN_MS, maxMs: STALL_ABORT_MS },
+    300_000,
+    { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: STALL_ABORT_MS },
 );
 
-export const PROVIDER_RETRY_BACKOFF_MS = Object.freeze([0, 1000, 2000, 4000, 8000]);
+// First retry has a small floor (250ms) instead of 0ms: an immediate reissue on
+// a transient 5xx burst lets parallel workers thundering-herd the backend in
+// lockstep (jitter alone can't decluster a 0ms base). Subsequent steps keep the
+// exponential schedule. Env-tunable via the providers' retryJitterRatio.
+export const PROVIDER_RETRY_BACKOFF_MS = Object.freeze([250, 1000, 2000, 4000, 8000]);
 export const PROVIDER_RETRY_MAX_ATTEMPTS = PROVIDER_RETRY_BACKOFF_MS.length;
 export const PROVIDER_RETRY_JITTER_RATIO = (() => {
     const raw = process.env.MIXDOG_PROVIDER_RETRY_JITTER_RATIO;
@@ -158,8 +206,8 @@ export const PROVIDER_RETRY_JITTER_RATIO = (() => {
     return 0.2;
 })();
 
-export function resolveAgentStallThresholds(role, env = process.env) {
-    const cfg = role ? getHiddenRole(role) : null;
+export function resolveAgentStallThresholds(agent, env = process.env) {
+    const cfg = agent ? getHiddenAgent(agent) : null;
     const cfgAbort = cfg?.stallCap?.idleSeconds > 0 ? cfg.stallCap.idleSeconds : STALL_ABORT_S;
     const envOverride = envThresholdSeconds(env);
     const abort = envOverride != null ? envOverride : cfgAbort;
@@ -175,8 +223,8 @@ export function resolveAgentStallThresholds(role, env = process.env) {
     return { warn, abort, firstByteAbort };
 }
 
-export function resolveAgentToolThresholdSeconds(role, thresholdSeconds) {
-    const cfg = role ? getHiddenRole(role) : null;
+export function resolveAgentToolThresholdSeconds(agent, thresholdSeconds) {
+    const cfg = agent ? getHiddenAgent(agent) : null;
     if (cfg?.stallCap?.toolRunningSeconds > 0) return cfg.stallCap.toolRunningSeconds;
     return thresholdSeconds;
 }

package/src/runtime/agent/orchestrator/tools/bash-session.mjs

@@ -44,7 +44,7 @@ import { invalidateBuiltinResultCache, analyzeShellCommandEffects, preflightShel
 import { markCodeGraphDirtyPaths, drainCodeGraphCache } from './code-graph-state.mjs';
 import { maybeRewriteWmicProcessCommand } from './shell-policy.mjs';
 import { _maybeEncodePowerShellCommand } from './shell-command.mjs';
-import { _captureTrackedMtimes, _trackedDriftNoteAfter, _injectionBlockTargets, getDedupedDestructiveWarnings } from './builtin/bash-tool.mjs';
+import { _captureTrackedMtimes, _trackedDriftNoteAfter, getDedupedDestructiveWarnings } from './builtin/bash-tool.mjs';
 import { scrubLoaderVars, scrubProviderSecrets } from './env-scrub.mjs';
 import { checkExecPolicyMessage } from './bash-policy-scan.mjs';
 import { startChildGuardian } from '../../../shared/child-guardian.mjs';

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

@@ -9,13 +9,22 @@
 // callers may pass either spelling (e.g. `glob` alias for grep, or
 // `file_path` alias for read.path).
 
-const MAX_INT = 100000;
-export const GREP_CONTEXT_MAX = 12;
+import { coerceShapeFlex, hasGlobMagic } from './path-utils.mjs';
 
+const MAX_INT = 100000;
+// Explicit grep context should be large enough to frame a function/block without
+// letting one match explode into a huge tool result. `content_with_context` still
+// defaults to 25 lines; this is only the upper bound for caller-supplied -A/-B/-C.
+export const GREP_CONTEXT_MAX = 200;
+
+// ripgrep-flavored aliases: models trained on `rg` emit short flags (-A/-B/-C),
+// long flags (--after-context / --before-context / --context), or snake/camel
+// spellings. All fold onto the canonical -A/-B/-C so a caller can write grep
+// the way they would write ripgrep on the shell.
 const GREP_CONTEXT_KEY_GROUPS = [
-    ['-A', ['-A', 'A', 'after', 'after_context', 'afterContext']],
-    ['-B', ['-B', 'B', 'before', 'before_context', 'beforeContext']],
-    ['-C', ['-C', 'C', 'context', 'context_lines', 'contextLines']],
+    ['-A', ['-A', 'A', 'after', 'after_context', 'afterContext', '--after-context', 'after-context', 'afterLines', 'after_lines']],
+    ['-B', ['-B', 'B', 'before', 'before_context', 'beforeContext', '--before-context', 'before-context', 'beforeLines', 'before_lines']],
+    ['-C', ['-C', 'C', 'context', 'context_lines', 'contextLines', '--context', 'contextN', 'around', 'surrounding']],
 ];
 
 function grepContextKeyPresent(a, k) {
@@ -76,11 +85,6 @@ function isStringOrStringArray(v) {
     return true;
 }
 
-function hasBackslashPipe(value) {
-    if (typeof value === 'string') return false;
-    return false;
-}
-
 function hasUnsupportedRipgrepRegex(value) {
     const values = Array.isArray(value) ? value : [value];
     return values.some((item) => {
@@ -103,8 +107,35 @@ function isFiniteInt(v) {
     return typeof v === 'number' && Number.isFinite(v) && Math.floor(v) === v;
 }
 
-function checkIntInRange(field, value, min, max) {
+// Lossless numeric-string coercion for integer-shaped args. Models
+// occasionally emit JSON-schema-violating numeric strings ("850",
+// "850.0") for fields the schema types as number (offset/limit/n/
+// head_limit/-A/-B/-C/context/line). Both are unambiguous integer
+// values, so coerce them to a real number before validating rather
+// than rejecting and forcing a retry turn. Non-integer or non-numeric
+// strings ("3.5", "soon") are left untouched and fall through to the
+// existing rejection below.
+function coerceIntegerString(v) {
+    if (typeof v !== 'string') return null;
+    const t = v.trim();
+    if (t === '' || !/^-?\d+(\.\d+)?$/.test(t)) return null;
+    const n = Number(t);
+    if (!Number.isFinite(n) || !Number.isInteger(n)) return null;
+    return n;
+}
+
+// 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) {
+    let value = a[field];
     if (value === undefined || value === null) return null;
+    if (typeof value === 'string') {
+        const coerced = coerceIntegerString(value);
+        if (coerced !== null) {
+            value = coerced;
+            a[field] = coerced;
+        }
+    }
     if (!isFiniteInt(value)) {
         return `Error: builtin arg "${field}" must be a finite integer (got ${describeType(value)})`;
     }
@@ -127,6 +158,38 @@ function hasOwn(o, k) {
     return o && Object.prototype.hasOwnProperty.call(o, k);
 }
 
+function isPresent(o, k) {
+    return hasOwn(o, k) && o[k] !== undefined && o[k] !== null;
+}
+
+function isNonEmptyPresent(o, k) {
+    return isPresent(o, k) && o[k] !== '';
+}
+
+// Strip trailing literal artifacts from a grep pattern: a literal two-char
+// "\n" (backslash + n) that ripgrep rejects outside multiline mode ("the
+// literal \"\\n\" is not allowed"), possibly preceded by concatenation
+// debris like `">` that rides along with it (e.g. a stray closing-tag
+// fragment glued on by string interpolation). `">` is ONLY stripped when
+// it is directly followed by one of those newline artifacts — a bare
+// trailing `">` with no newline riding along (e.g. a legit HTML/JSX
+// attribute pattern like `class="active">`) is a real search target and
+// must survive untouched. A \n in the middle of a pattern is also left
+// untouched; only the tail is ever trimmed.
+function stripTrailingPatternArtifacts(v) {
+    if (typeof v !== 'string') return v;
+    let out = v;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        if (out.endsWith('">\n')) { out = out.slice(0, -3); changed = true; continue; }
+        if (out.endsWith('">\\n')) { out = out.slice(0, -4); changed = true; continue; }
+        if (out.endsWith('\n')) { out = out.slice(0, -1); changed = true; continue; }
+        if (out.endsWith('\\n')) { out = out.slice(0, -2); changed = true; continue; }
+    }
+    return out;
+}
+
 // ---- per-tool guards ----
 
 function guardGrep(a) {
@@ -135,6 +198,15 @@ function guardGrep(a) {
     // glob (file filter) aliases
     const globKeys = ['glob', 'file_pattern', 'include', 'files'];
 
+    // Lossless cleanup of trailing artifacts before validation (item 5b).
+    for (const k of patternKeys) {
+        if (hasOwn(a, k)) {
+            a[k] = Array.isArray(a[k])
+                ? a[k].map(stripTrailingPatternArtifacts)
+                : stripTrailingPatternArtifacts(a[k]);
+        }
+    }
+
     const hasPattern = patternKeys.some((k) => hasOwn(a, k));
     const hasGlob = globKeys.some((k) => hasOwn(a, k));
     if (!hasPattern && !hasGlob) {
@@ -144,9 +216,6 @@ 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) && hasBackslashPipe(a[k])) {
-            return `Error: grep arg "${k}" contains \\|. Use pattern:["a","b"] for OR terms, or unescaped | for regex alternation.`;
-        }
         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.`;
         }
@@ -165,34 +234,93 @@ function guardGrep(a) {
             return `Error: grep arg "${k}" contains multiple absolute paths in one string. Use one common parent path plus glob, or separate grep calls.`;
         }
     }
-    // numeric clamps (grep context 0..12, mirrors read line-context tightening)
     for (const k of ['head_limit', 'offset']) {
-        const err = checkIntInRange(k, a[k], 0, MAX_INT);
+        const err = checkIntInRange(a, k, 0, MAX_INT);
         if (err) return err;
     }
     for (const k of ['-A', '-B', '-C', 'context']) {
-        const err = checkIntInRange(k, a[k], 0, GREP_CONTEXT_MAX);
+        const err = checkIntInRange(a, k, 0, GREP_CONTEXT_MAX);
         if (err) return err;
     }
     // output_mode / mode enum
     const modeKeys = ['output_mode', 'mode'];
-    const allowed = new Set(['files_with_matches', 'content', 'count']);
+    const allowed = new Set(['files_with_matches', 'content', 'content_with_context', 'count']);
     for (const k of modeKeys) {
         if (hasOwn(a, k)) {
+            // Some callers concatenate a second field's value onto the enum
+            // string with a literal newline (e.g. "content_with_context\ntrue").
+            // If the first line/token is a valid enum value, truncate to it
+            // losslessly rather than rejecting a shape that unambiguously
+            // names a real mode (item 5a).
+            if (typeof a[k] === 'string' && a[k].includes('\n')) {
+                const firstLine = a[k].split('\n')[0].trim();
+                const firstToken = firstLine.split(/\s+/)[0];
+                if (allowed.has(firstToken)) a[k] = firstToken;
+            }
             if (!isString(a[k]) || !allowed.has(a[k])) {
-                return `Error: grep arg "${k}" must be one of files_with_matches|content|count (got ${JSON.stringify(a[k])})`;
+                return `Error: grep arg "${k}" must be one of content_with_context|content|files_with_matches|count (got ${JSON.stringify(a[k])})`;
             }
         }
     }
     return null;
 }
 
+// Convert a {line, context} pair into {offset, limit}, matching the
+// read-args.mjs private file#Lx compatibility normalizer's semantics
+// (offset = startLine - 1, limit = endLine - startLine + 1, clamped at 0)
+// generalized to a symmetric window: startLine = line - context,
+// endLine = line + context. offset/limit are treated as authoritative —
+// if either is already present, line/context are dropped unused rather
+// than overriding an explicit window. Mutates obj in place. Returns an
+// error string or null.
+function applyLineContextWindow(obj, labelPrefix) {
+    for (const k of ['line', 'context', 'offset', 'limit']) {
+        if (isPresent(obj, k) && typeof obj[k] === 'string') {
+            const coerced = coerceIntegerString(obj[k]);
+            if (coerced !== null) obj[k] = coerced;
+        }
+    }
+    const hasLine = isPresent(obj, 'line');
+    const hasContext = isPresent(obj, 'context');
+    if (!hasLine && !hasContext) return null;
+    if (isPresent(obj, 'offset') || isPresent(obj, 'limit')) {
+        delete obj.line;
+        delete obj.context;
+        return null;
+    }
+    if (!hasLine) {
+        return `Error: read arg "${labelPrefix}context" requires "${labelPrefix}line" to compute a window`;
+    }
+    if (!isFiniteInt(obj.line) || obj.line < 1) {
+        return `Error: read arg "${labelPrefix}line" must be a finite integer >= 1 (got ${describeType(obj.line)})`;
+    }
+    let ctx = 0;
+    if (hasContext) {
+        if (!isFiniteInt(obj.context) || obj.context < 0) {
+            return `Error: read arg "${labelPrefix}context" must be a non-negative finite integer (got ${describeType(obj.context)})`;
+        }
+        ctx = obj.context;
+    }
+    obj.offset = Math.max(0, obj.line - 1 - ctx);
+    obj.limit = 2 * ctx + 1;
+    delete obj.line;
+    delete obj.context;
+    return null;
+}
+
 function guardRead(a) {
     // path / file_path alias OR path may itself be array
     const hasPath = hasOwn(a, 'path') || hasOwn(a, 'file_path');
     if (!hasPath) {
         return 'Error: read requires "path" (or alias file_path).';
     }
+    // Some providers/models send a batched path array as a JSON string despite
+    // the schema. The executor already accepts that shape via coerceShapeFlex(),
+    // but validation runs first; apply the same lossless shape coercion here so
+    // valid batched reads do not waste a retry turn.
+    if (hasOwn(a, 'path')) {
+        a.path = coerceShapeFlex(a.path);
+    }
     // path can be string | string[] | object[]; file_path is string
     if (hasOwn(a, 'path')) {
         const p = a.path;
@@ -200,16 +328,36 @@ function guardRead(a) {
         if (!ok) {
             return `Error: read arg "path" must be string, string[], or object[] (got ${describeType(p)})`;
         }
+        if (Array.isArray(p)) {
+            for (let i = 0; i < p.length; i++) {
+                const entry = p[i];
+                if (typeof entry === 'string') continue;
+                if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                    return `Error: read arg "path[${i}]" must be string or {path,offset,limit} object (got ${describeType(entry)})`;
+                }
+                const err = applyLineContextWindow(entry, `path[${i}].`);
+                if (err) return err;
+                for (const ek of ['offset', 'limit']) {
+                    const eErr = checkIntInRange(entry, ek, 0, MAX_INT);
+                    if (eErr) return eErr.replace(`"${ek}"`, `"path[${i}].${ek}"`);
+                }
+            }
+        }
     }
     if (hasOwn(a, 'file_path') && !isNonEmptyString(a.file_path)) {
         return `Error: read arg "file_path" must be a non-empty string (got ${describeType(a.file_path)})`;
     }
-    if (hasOwn(a, 'line') && (hasOwn(a, 'offset') || hasOwn(a, 'limit'))) {
-        return 'Error: read window args conflict — use exactly one window family: line+context OR offset+limit OR symbol.';
+    // Read's public surface is offset/limit, but a top-level line/context pair
+    // is a deterministic, lossless spelling of the same window (matching
+    // read-args.mjs's internal file:line normalizer semantics); convert it
+    // instead of rejecting. offset/limit, if already present, win outright.
+    {
+        const err = applyLineContextWindow(a, '');
+        if (err) return err;
     }
     // offset >=0
     {
-        const err = checkIntInRange('offset', a.offset, 0, MAX_INT);
+        const err = checkIntInRange(a, 'offset', 0, MAX_INT);
         if (err) return err;
     }
     // limit: >=1 = explicit cap; 0 = unlimited sentinel (read-formatting maps 0 to
@@ -218,12 +366,7 @@ function guardRead(a) {
     // break that unbounded-batch contract. A placeholder limit:0 from a symbol
     // read is stripped on the symbol path. Negatives still error.
     {
-        const err = checkIntInRange('limit', a.limit, 0, MAX_INT);
-        if (err) return err;
-    }
-    // context 0..200
-    {
-        const err = checkIntInRange('context', a.context, 0, 200);
+        const err = checkIntInRange(a, 'limit', 0, MAX_INT);
         if (err) return err;
     }
     // n 0..10000 — accept 0 rather than erroring: the read-mode handlers coerce
@@ -232,7 +375,7 @@ function guardRead(a) {
     // n is moot. Rejecting 0 only forced a wasted retry turn (the whole point of
     // these reads is to land in one shot). Negatives remain a real error.
     if (hasOwn(a, 'n') && a.n !== undefined && a.n !== null) {
-        const err = checkIntInRange('n', a.n, 0, 10000);
+        const err = checkIntInRange(a, 'n', 0, 10000);
         if (err) return err;
     }
     return null;
@@ -256,7 +399,10 @@ function guardShell(a) {
         return 'Error: shell arg "command" must be a non-empty string';
     }
     if (process.platform === 'win32' && !hasOwn(a, 'shell') && hasWindowsDrivePath(a.command)) {
-        return "Error: shell command contains a Windows drive path; set shell:'powershell' or convert paths for shell:'bash'.";
+        // A Windows drive path (C:\...) is unambiguous evidence the caller
+        // wants the Windows shell; default it losslessly instead of forcing
+        // a retry turn just to add shell:'powershell'.
+        a.shell = 'powershell';
     }
     for (const k of ['cwd', 'workdir']) {
         if (hasOwn(a, k) && (a[k] === undefined || a[k] === null || a[k] === '')) {
@@ -331,12 +477,28 @@ function guardFind(a) {
 
 function guardGlob(a) {
     // path alias root; pattern aliases glob/name/file_pattern
+    const globPatternKeys = ['pattern', 'glob', 'name', 'file_pattern'];
+    const hasAnyPattern = globPatternKeys.some((k) => isNonEmptyPresent(a, k));
+    // Skip the default when `path` itself carries glob magic (*?[{) — that
+    // shape means "path IS the pattern" and is handled by executeGlobTool's
+    // own path-magic fallback (splitting path into baseDir + pattern).
+    // Injecting pattern:'*' here would override that fallback and silently
+    // change "src/**/*.mjs" into "match everything under src/**/*.mjs".
+    const pathHasGlobMagic = Array.isArray(a.path)
+        ? a.path.some((p) => hasGlobMagic(p))
+        : hasGlobMagic(a.path);
+    if (!hasAnyPattern && isNonEmptyPresent(a, 'path') && !pathHasGlobMagic) {
+        // Missing pattern with a real path is an unambiguous "match
+        // everything under this path" request; default it instead of
+        // erroring out via globMissingPatternMessage() downstream.
+        a.pattern = '*';
+    }
     for (const k of ['path', 'root']) {
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: glob arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
     }
-    for (const k of ['pattern', 'glob', 'name', 'file_pattern']) {
+    for (const k of globPatternKeys) {
         if (hasOwn(a, k) && !isStringOrStringArray(a[k])) {
             return `Error: glob arg "${k}" must be string or string[] (got ${describeType(a[k])})`;
         }
@@ -359,7 +521,7 @@ function guardGlob(a) {
 // find_symbol, references, callers, imports, dependents.
 const CODE_GRAPH_MODES = new Set([
     'overview', 'imports', 'dependents', 'related', 'impact',
-    'symbols', 'find_symbol', 'search', 'references', 'callers', 'callees', 'prewarm',
+    'symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees', 'prewarm',
 ]);
 
 function guardCodeGraph(a) {