mixdog 0.9.38 → 0.9.39

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

@@ -8,12 +8,13 @@ import * as fsp from 'fs/promises';
 import { randomBytes } from 'crypto';
 import { join } from 'path';
 import { Worker } from 'worker_threads';
-import { getPluginData } from '../config.mjs';
+import { getPluginData, loadConfig } 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 { rotateBoundedLog, PLUGIN_LOG_MAX_BYTES, PLUGIN_LOG_KEEP_BYTES } from '../../../../lib/mixdog-debug.cjs';
+import { resolveAgentTerminalReapMs } from '../../../../session-runtime/config-helpers.mjs';
 import {
     summaryIndexPath,
     _sessionSummary,
@@ -600,8 +601,37 @@ export function markSessionClosed(id, reason = 'manual') {
     _clearDebounce(id);
     const existing = loadSession(id);
     if (!existing) return null;
-    const newGen = (typeof existing.generation === 'number' ? existing.generation : 0) + 1;
-    const tombstone = { ...existing, closed: true, closedReason: reason, status: 'closed', generation: newGen, updatedAt: Date.now() };
+    // Re-close idempotence: a session that is ALREADY tombstoned keeps its
+    // ORIGINAL close time (updatedAt) and generation. The old code refreshed
+    // updatedAt=Date.now() on every call, so the 5-min idle sweep re-closing a
+    // stale summary row reset the tombstone age each cycle — tombstones never
+    // matured past the sweep threshold (immortality loop). Preserving the
+    // original close time lets the age accumulate so the tombstone sweep can
+    // reclaim it.
+    //
+    // The alreadyClosed / original-close-time / generation decision MUST come
+    // from the ON-DISK JSON, read cache-bypassing — NOT from loadSession(),
+    // which can serve a stale in-memory OPEN payload (a pending debounced save
+    // or a _liveSessions entry) after a late save. Deciding off that stale open
+    // copy would make a re-close of an already-tombstoned session look like a
+    // FIRST close and reset updatedAt+generation, resurrecting the exact
+    // immortality refresh this guard prevents. The disk file is the
+    // authoritative tombstone state.
+    let onDisk = null;
+    try { onDisk = JSON.parse(readFileSync(sessionPath(id), 'utf-8')); }
+    catch { onDisk = null; }
+    const alreadyClosed = onDisk
+        ? (onDisk.closed === true || onDisk.status === 'closed')
+        : (existing.closed === true);
+    // When the on-disk copy is already closed, base the (idempotent) tombstone
+    // rewrite on IT rather than on `existing`, so a stale open in-memory
+    // payload can never clobber the persisted tombstone's content/fields.
+    const base = (alreadyClosed && onDisk) ? onDisk : existing;
+    const closeTime = (alreadyClosed && typeof base.updatedAt === 'number' && base.updatedAt > 0)
+        ? base.updatedAt
+        : Date.now();
+    const newGen = (typeof base.generation === 'number' ? base.generation : 0) + (alreadyClosed ? 0 : 1);
+    const tombstone = { ...base, closed: true, closedReason: alreadyClosed ? (base.closedReason || reason) : reason, status: 'closed', generation: newGen, updatedAt: closeTime };
     // Bypass the queue + guard — this IS the tombstone write.
     const target = sessionPath(id);
     const tmp = target + '.' + randomBytes(6).toString('hex') + '.tmp';
@@ -622,7 +652,10 @@ export function markSessionClosed(id, reason = 'manual') {
     // it reflects the session's full lifetime including the close turn.
     try {
         const _dataDir = getPluginData();
-        if (_dataDir) {
+        // Emit the close metric only on the FIRST close — a re-close of an
+        // already-tombstoned session is a no-op idempotent write and must not
+        // spam the close log or double-count lifetimes.
+        if (_dataDir && !alreadyClosed) {
             const _ts = new Date().toISOString();
             const _lifeMs = (typeof existing.createdAt === 'number' && existing.createdAt > 0)
                 ? (tombstone.updatedAt - existing.createdAt)
@@ -722,16 +755,24 @@ export function deleteSession(id, options = {}) {
     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
-// Completed agents (idle/done/error) live until terminal reap - must
-// match TERMINAL_REAP_MS / _scheduleBridgeReap (3_600_000) in index.mjs and
-// agent stall watchdog, so the store sweep is the durable 1h reaper.
-const AGENT_TERMINAL_TTL_MS = 60 * 60 * 1000;
 const AGENT_TERMINAL_STATUSES = new Set(['idle', 'done', 'error']);
 // Hard wall-clock ceiling for sessions stuck in status='running'. The
 // stream-watchdog should abort stalled streams within ~120s, but if it misses
 // one (process crash, watchdog not started, provider never returned), this
 // backstop reclaims the file so the sweep doesn't leak zombies indefinitely.
 const RUNNING_STALL_MS = 10 * 60 * 1000;
+// Retention cap for resumable OPEN (non-tombstone) sessions. Lead/user resume
+// closes sessions with { tombstone:false } — the runtime detaches but the
+// session JSON stays open/resumable and is never lifecycle-closed, so without
+// a cap the sessions/ dir grows without bound (observed 782 open files). The
+// sweep prunes open sessions past EITHER bound: older than 14d, or beyond the
+// newest 300 (oldest first). The cap targets ONLY ephemeral agent/ownerless
+// sessions — explicit USER-owned conversations are never auto-pruned (deleting
+// a user's history, including the current foreground session which is idle
+// during a gated sweep, is unacceptable). A session with a live runtime entry
+// (options.isSessionLive) is additionally protected as defense-in-depth.
+const RESUMABLE_OPEN_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+const RESUMABLE_OPEN_MAX_COUNT = 300;
 
 export function listStoredSessions() {
     const dir = getStoreDir();
@@ -800,12 +841,44 @@ export function sweepStaleSessions(ttlMs, options = {}) {
     }
     const maxAge = ttlMs || DEFAULT_SESSION_TTL_MS;
     const sweepIdle = options.sweepIdle !== false;
+    let terminalReapConfig = null;
+    try { terminalReapConfig = loadConfig({ secrets: false }); } catch { /* built-ins remain available */ }
     const tombstoneMaxAgeMs = Number(options.tombstoneMaxAgeMs);
     const sweepTombstones = Number.isFinite(tombstoneMaxAgeMs) && tombstoneMaxAgeMs > 0;
+    // Retention cap for resumable open sessions runs only on the idle sweep
+    // (never on a tombstone-only pass). isSessionLive protects the current /
+    // actively-running sessions from being pruned by the retention cap.
+    const isSessionLive = typeof options.isSessionLive === 'function' ? options.isSessionLive : null;
+    const retainOpen = sweepIdle && options.retainOpenSessions !== false;
+    const _optAge = Number(options.openMaxAgeMs);
+    const _optCount = Number(options.openMaxCount);
+    const openMaxAgeMs = Number.isFinite(_optAge) && _optAge > 0 ? _optAge : RESUMABLE_OPEN_MAX_AGE_MS;
+    const openMaxCount = Number.isFinite(_optCount) && _optCount >= 0 ? _optCount : RESUMABLE_OPEN_MAX_COUNT;
     const dir = getStoreDir();
     if (!existsSync(dir))
         return { cleaned: 0, remaining: 0, details: [], tombstonesCleaned: 0, tombstoneDetails: [], tombstoneErrors: [] };
-    const summaries = listStoredSessionSummaries();
+    // Reconcile the index-derived candidate set with a direct directory scan:
+    // the summary index is a best-effort sidecar that can lag far behind disk
+    // (thousands of on-disk .json files may be absent from a smaller index).
+    // Any such orphan closed+mature tombstone would otherwise be unreachable by
+    // this sweep and accumulate forever. Union the index rows with every
+    // on-disk .json id, deduped by id; synthetic { id } rows are sufficient
+    // because the loop below re-reads all lifecycle truth from disk. This stays
+    // sweep-local and does NOT change listStoredSessionSummaries for other
+    // callers. Steady-state cost is one readdirSync plus cheap per-orphan reads.
+    const indexRows = listStoredSessionSummaries();
+    const summaries = indexRows;
+    try {
+        const seen = new Set();
+        for (const row of indexRows) { if (row?.id) seen.add(row.id); }
+        for (const f of readdirSync(dir)) {
+            if (!f.endsWith('.json')) continue;
+            const id = f.slice(0, -5);
+            if (!id || seen.has(id)) continue;
+            seen.add(id);
+            summaries.push({ id });
+        }
+    } catch { /* dir scan failure — fall back to index rows only */ }
     const now = Date.now();
     let cleaned = 0;
     let remaining = 0;
@@ -813,6 +886,11 @@ export function sweepStaleSessions(ttlMs, options = {}) {
     const details = [];
     const tombstoneDetails = [];
     const tombstoneErrors = [];
+    // Retention-cap bookkeeping: collect surviving open (non-tombstone)
+    // sessions here, then prune oldest-first after the main loop.
+    const openCandidates = [];
+    let openPruned = 0;
+    const openPrunedDetails = [];
     for (const row of summaries) {
         try {
             if (!row?.id) continue;
@@ -828,38 +906,116 @@ export function sweepStaleSessions(ttlMs, options = {}) {
                 const hbPath = join(dir, `${row.id}.hb`);
                 if (existsSync(hbPath)) heartbeatMtime = statSync(hbPath).mtimeMs || 0;
             } catch { /* .hb unavailable — fall back to JSON fields */ }
-            const freshnessGateMs = sweepIdle ? maxAge : (sweepTombstones ? tombstoneMaxAgeMs : 0);
-            const newestKnown = Math.max(row.updatedAt || 0, row.lastHeartbeatAt || 0, row.createdAt || 0, jsonMtime, heartbeatMtime);
-            if (freshnessGateMs > 0 && newestKnown > 0 && now - newestKnown <= freshnessGateMs) {
-                remaining++;
-                continue;
+            // Truth source: the summary index is a deferred/best-effort sidecar,
+            // so a row can still claim status='idle'/open while the session JSON
+            // was already tombstoned. Read the real session JSON BEFORE the
+            // freshness gate so closed-ness is decided from AUTHORITATIVE on-disk
+            // state — otherwise idle-sweep re-closes an already-closed session via
+            // markSessionClosed (which, pre-fix, reset the tombstone age every
+            // 5-min cycle → immortality loop).
+            let raw = null;
+            try { raw = readFileSync(jsonPath, 'utf-8'); }
+            catch { /* racing unlink / transient read failure */ }
+            let actual = null;
+            let diskClosed;
+            if (raw == null) {
+                diskClosed = (row.closed === true || row.status === 'closed');
+            } else {
+                // Cheap top-level scan avoids allocating the whole messages array
+                // just to read the closed flag for the (common) fresh open
+                // session the gate will skip; full-parse only when the scan can't
+                // resolve the top-level flag.
+                const scan = scanTopLevelLifecycle(raw);
+                if (scan && typeof scan.closed === 'boolean') {
+                    diskClosed = scan.closed;
+                } else {
+                    try { actual = JSON.parse(raw); } catch { actual = null; }
+                    diskClosed = actual
+                        ? (actual.closed === true || actual.status === 'closed')
+                        : (row.closed === true || row.status === 'closed');
+                }
             }
-            // Already-closed tombstones are handled here before heartbeat
-            // sidecar checks; they do not need liveness probing.
-            if (row.closed === true || row.status === 'closed') {
-                if (sweepTombstones) {
-                    const updated = Number(row.updatedAt);
-                    const age = now - updated;
-                    if (Number.isFinite(updated) && age >= tombstoneMaxAgeMs) {
-                        try {
-                            if (deleteSession(row.id, { deferSummaryUpdate: true })) {
-                                tombstonesCleaned++;
-                                tombstoneDetails.push({ id: row.id, ageSeconds: Math.floor(age / 1000) });
-                                continue;
-                            }
-                        } catch (err) {
-                            tombstoneErrors.push({ id: row.id, message: err?.message || String(err) });
-                            remaining++;
+            if (diskClosed) {
+                // Closed sessions are EXEMPT from the freshness gate: a tombstone
+                // whose file/hb mtime keeps getting bumped would otherwise stay
+                // perpetually "fresh" and never mature. Maturity is governed ONLY
+                // by the ORIGINAL close time (disk updatedAt, not row.updatedAt
+                // which a stale row may carry from before the close).
+                if (!actual && raw != null) { try { actual = JSON.parse(raw); } catch { actual = null; } }
+                const closedAt = Number(actual?.updatedAt ?? row.updatedAt);
+                const age = now - closedAt;
+                if (sweepTombstones && Number.isFinite(closedAt) && age >= tombstoneMaxAgeMs) {
+                    try {
+                        if (deleteSession(row.id, { deferSummaryUpdate: true })) {
+                            tombstonesCleaned++;
+                            tombstoneDetails.push({ id: row.id, ageSeconds: Math.floor(age / 1000) });
                             continue;
                         }
+                    } catch (err) {
+                        tombstoneErrors.push({ id: row.id, message: err?.message || String(err) });
+                        remaining++;
+                        continue;
                     }
                 }
+                // Repair a stale summary row that still claimed the session was
+                // open: reflect the real closed state so the next sweep sees the
+                // correct closed=true/updatedAt and never re-closes it.
+                if (actual && !(row.closed === true || row.status === 'closed')) {
+                    try { _upsertSessionSummary(actual); } catch { /* best-effort */ }
+                }
+                remaining++;
+                continue;
+            }
+            // Parse the open record before its freshness gate: completed agents
+            // use their provider's Advanced terminal duration rather than the
+            // general sweep cadence. A short provider override must therefore
+            // not be hidden behind the default 5-minute gate.
+            if (!actual && raw != null) { try { actual = JSON.parse(raw); } catch { actual = null; } }
+            const gateOwner = (actual && typeof actual.owner === 'string' && actual.owner.length > 0)
+                ? actual.owner : row.owner;
+            const gateStatus = (actual && typeof actual.status === 'string') ? actual.status : row.status;
+            const gateProvider = (actual && typeof actual.provider === 'string') ? actual.provider : row.provider;
+            const isCompletedAgentForGate = isAgentOwner({ owner: gateOwner })
+                && AGENT_TERMINAL_STATUSES.has(gateStatus);
+            const terminalReapMsForGate = isCompletedAgentForGate
+                ? resolveAgentTerminalReapMs(terminalReapConfig, gateProvider)
+                : null;
+            if (isCompletedAgentForGate && terminalReapMsForGate == null) {
                 remaining++;
                 continue;
             }
+            // Freshness gate — OPEN sessions only (closed sessions handled and
+            // `continue`d above). Recently-touched open sessions are skipped
+            // cheaply here.
+            const freshnessGateMs = sweepIdle
+                ? (terminalReapMsForGate ?? maxAge)
+                : (sweepTombstones ? tombstoneMaxAgeMs : 0);
+            const newestKnown = Math.max(row.updatedAt || 0, row.lastHeartbeatAt || 0, row.createdAt || 0, jsonMtime, heartbeatMtime);
+            if (freshnessGateMs > 0 && newestKnown > 0 && now - newestKnown <= freshnessGateMs) {
+                remaining++;
+                continue;
+            }
+            // Prefer the AUTHORITATIVE on-disk JSON over the best-effort (and
+            // possibly stale) summary row for every open/idle liveness and
+            // ownership decision below — a stale row must not close or prune the
+            // wrong session. Full-parse here if the cheap scan skipped it.
+            if (!actual && raw != null) { try { actual = JSON.parse(raw); } catch { actual = null; } }
+            const effOwner = (actual && typeof actual.owner === 'string' && actual.owner.length > 0)
+                ? actual.owner : row.owner;
+            const ownerRef = { owner: effOwner };
+            const effStatus = (actual && typeof actual.status === 'string') ? actual.status : row.status;
+            const effUpdatedAt = Number(actual?.updatedAt) > 0 ? Number(actual.updatedAt) : (row.updatedAt || 0);
+            const effLastHb = Number(actual?.lastHeartbeatAt) > 0 ? Number(actual.lastHeartbeatAt) : (row.lastHeartbeatAt || 0);
+            const effCreatedAt = Number(actual?.createdAt) > 0 ? Number(actual.createdAt) : (row.createdAt || 0);
+            const effBashId = (actual && actual.implicitBashSessionId) || row.implicitBashSessionId || null;
+            const effProvider = (actual && typeof actual.provider === 'string') ? actual.provider : row.provider;
             // Sweep agent-owned and ownerless (legacy) sessions; skip explicit
-            // user sessions before touching heartbeat sidecars.
-            if (typeof row.owner === 'string' && row.owner.length > 0 && !isAgentOwner(row)) {
+            // user sessions before touching heartbeat sidecars. USER-owned
+            // conversations are NEVER added to the retention-cap candidate set —
+            // the cap must not auto-delete user history (nor the current
+            // foreground session, which is idle during a gated sweep). Only the
+            // ephemeral agent/ownerless sessions below feed the cap.
+            if (typeof effOwner === 'string' && effOwner.length > 0 && !isAgentOwner(ownerRef)) {
                 remaining++;
                 continue;
             }
@@ -870,18 +1026,19 @@ export function sweepStaleSessions(ttlMs, options = {}) {
             // Prefer .hb sidecar mtime — updated at tight cadence (≤5s) without
             // serialising the full JSON, so it reflects true liveness more
             // accurately than the JSON timestamp fields.
-            let lastActive = row.lastHeartbeatAt || row.updatedAt || row.createdAt || 0;
+            let lastActive = effLastHb || effUpdatedAt || effCreatedAt || 0;
             if (heartbeatMtime) lastActive = Math.max(lastActive, heartbeatMtime);
             // Running sessions are normally reaped by the stream-watchdog
             // within ~120s. Skip them here unless they've been silent past
             // RUNNING_STALL_MS, at which point they are treated as zombies.
-            if (row.status === 'running' && now - lastActive <= RUNNING_STALL_MS) {
+            if (effStatus === 'running' && now - lastActive <= RUNNING_STALL_MS) {
                 remaining++;
                 continue;
             }
-            const isCompletedAgent = isAgentOwner(row)
-                && AGENT_TERMINAL_STATUSES.has(row.status);
-            const sessionMaxAge = isCompletedAgent ? AGENT_TERMINAL_TTL_MS : maxAge;
+            const isCompletedAgent = isAgentOwner(ownerRef)
+                && AGENT_TERMINAL_STATUSES.has(effStatus);
+            const terminalReapMs = isCompletedAgent ? terminalReapMsForGate : null;
+            const sessionMaxAge = terminalReapMs ?? maxAge;
             if (now - lastActive > sessionMaxAge) {
                 try { markSessionClosed(row.id, 'idle-sweep'); }
                 catch (err) {
@@ -891,16 +1048,40 @@ export function sweepStaleSessions(ttlMs, options = {}) {
                 cleaned++;
                 details.push({
                     id: row.id,
-                    owner: row.owner || 'unknown',
+                    owner: effOwner || 'unknown',
                     idleMinutes: Math.round((now - lastActive) / 60000),
-                    bashSessionId: row.implicitBashSessionId || null,
+                    bashSessionId: effBashId,
                 });
             } else {
+                if (retainOpen) openCandidates.push({ id: row.id, lastActive });
                 remaining++;
             }
         }
         catch { /* skip corrupt */ }
     }
+    // ── Retention cap: prune resumable open (non-tombstone) sessions ──────────
+    // Newest-first: keep the most recent openMaxCount, prune anything older than
+    // openMaxAgeMs OR beyond the count. Live/current sessions (isSessionLive)
+    // are never pruned but still occupy a kept slot.
+    if (retainOpen && openCandidates.length > 0) {
+        openCandidates.sort((a, b) => (b.lastActive || 0) - (a.lastActive || 0));
+        let kept = 0;
+        for (const c of openCandidates) {
+            if (isSessionLive && isSessionLive(c.id)) { kept++; continue; }
+            const tooOld = openMaxAgeMs > 0 && now - (c.lastActive || 0) > openMaxAgeMs;
+            const overCount = kept >= openMaxCount;
+            if (!tooOld && !overCount) { kept++; continue; }
+            try {
+                if (deleteSession(c.id, { deferSummaryUpdate: true })) {
+                    openPruned++;
+                    openPrunedDetails.push({ id: c.id, ageSeconds: Math.floor((now - (c.lastActive || 0)) / 1000) });
+                    if (remaining > 0) remaining--;
+                } else {
+                    kept++;
+                }
+            } catch { kept++; }
+        }
+    }
     // Orphan .hb reap: a heartbeat sidecar whose .json no longer exists is dead
     // weight once it is also stale (older than maxAge) — the session JSON was
     // swept/closed but the .hb lingered (a pre-fix orphaned heartbeat). The
@@ -920,11 +1101,11 @@ export function sweepStaleSessions(ttlMs, options = {}) {
     // 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) {
+    if (tombstoneDetails.length > 0 || openPrunedDetails.length > 0) {
         try {
-            const deletedIds = new Set(tombstoneDetails.map((d) => d.id));
+            const deletedIds = new Set([...tombstoneDetails, ...openPrunedDetails].map((d) => d.id));
             _pruneSummaryIndexIds(deletedIds);
         } catch { /* summary index is best-effort */ }
     }
-    return { cleaned, remaining, details, tombstonesCleaned, tombstoneDetails, tombstoneErrors };
+    return { cleaned, remaining, details, tombstonesCleaned, tombstoneDetails, tombstoneErrors, openPruned, openPrunedDetails };
 }

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

@@ -79,6 +79,11 @@ function clearGrepContextKeys(args, keys) {
 /** Lead-facing grep context: canonicalize aliases and clamp explicit values (overrides still apply). */
 export function applyGrepContextLeadPolicy(args) {
     if (!args || typeof args !== 'object' || Array.isArray(args)) return;
+    // Idempotent guard: the outer builtin guard (validateBuiltinArgs) and the
+    // executor (executeGrepTool) both call this on the SAME args object. The
+    // first pass folds aliases onto -A/-B/-C and clamps; a second pass would
+    // recompute the same folding for no effect. Skip once applied.
+    if (args._grepContextPolicyApplied) return;
     for (const [canonical, keys] of GREP_CONTEXT_KEY_GROUPS) {
         const found = firstNonZeroGrepContextArg(args, keys) || firstGrepContextArg(args, keys);
         if (!found) continue;
@@ -87,6 +92,12 @@ export function applyGrepContextLeadPolicy(args) {
         clearGrepContextKeys(args, keys);
         args[canonical] = shaped;
     }
+    // Non-enumerable so it never leaks into arg spreads, cache keys, or output.
+    try {
+        Object.defineProperty(args, '_grepContextPolicyApplied', {
+            value: true, enumerable: false, configurable: true, writable: true,
+        });
+    } catch { args._grepContextPolicyApplied = true; }
 }
 
 function isString(v) {
@@ -435,7 +446,7 @@ function guardGrep(a) {
     const grepMode = a.output_mode || a.mode;
     const hasExplicitCtx = ['-A', '-B', '-C', 'context'].some((k) => grepContextKeyPresent(a, k));
     const isCountOrFiles = grepMode === 'files_with_matches' || grepMode === 'count';
-    if (!isCountOrFiles && (grepMode === 'content_with_context' || hasExplicitCtx)) {
+    if (!isCountOrFiles && (grepMode == null || grepMode === 'content_with_context' || hasExplicitCtx)) {
         const hl = Number(a.head_limit);
         if (grepContextKeyPresent(a, 'head_limit') && Number.isFinite(hl) && hl > GREP_CTX_HEAD_LIMIT_MAX) {
             a.head_limit = GREP_CTX_HEAD_LIMIT_MAX;

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

@@ -39,7 +39,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read verified file path(s); guessed path → find first (same turn as other probes). Batch paths/regions as real arrays in one call. Not for directory listing.',
+        description: 'Read verified file path(s); guessed path/name → find first. Array-first: batch paths/regions as real arrays in one call; put targets in path[] or {path,offset,limit}[] and read the whole logical unit. Content_with_context is actionable; do not page or re-read returned spans. Not for directory listing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -58,29 +58,31 @@ export const BUILTIN_TOOLS = [
                                             offset: { type: 'number', minimum: 0 },
                                             limit: { type: 'number', minimum: 1 },
                                         },
+                                        required: ['path'],
                                     },
                                 ],
                             },
                             minItems: 1,
                         },
                     ],
-                    description: 'Verified file path. Batch spans via path[] or {path,offset,limit}[] regions. Pass arrays directly; JSON strings are legacy recovery only.',
+                    description: 'Verified file path; use {path,offset,limit}[] targets. Pass arrays directly; JSON strings are legacy recovery only.',
                 },
-                offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip before reading; 0 starts at line 1. Continue with offset:N.' },
-                limit: { type: 'number', minimum: 1, description: 'Numeric max lines to return after offset.' },
+                offset: { type: 'number', minimum: 0, description: 'Numeric lines to skip; 0 starts at line 1. Continue with offset:N.' },
+                limit: { type: 'number', minimum: 1, description: 'Numeric max lines after offset.' },
             },
+            required: ['path'],
         },
     },
     {
         name: 'shell',
         title: 'Mixdog Shell',
         annotations: { title: 'Mixdog Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run programs or change system state. Set shell: powershell or bash. Not for reading, listing, or searching files. Batch independent commands: ;/&& in one call, or parallel calls in the same turn.${_shellSyntaxCheat} ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
+        description: `Run programs or change system state; set shell: powershell or bash. Not for reading, listing or searching. Shell/write calls are serial; use ;/&& only for intentional in-command sequencing.${_shellSyntaxCheat} ${TOOL_ASYNC_EXECUTION_CONTRACT}`,
         inputSchema: {
             type: 'object',
             properties: {
                 command: { type: 'string', description: 'Command.' },
-                cwd: { type: 'string', description: 'Working directory. Persists across shell calls in a session — omit to reuse the previous command\'s directory (e.g. after cd); pass an absolute path to change it.' },
+                cwd: { type: 'string', description: 'Working directory; persists across calls. Omit to reuse; absolute path changes it.' },
                 timeout: { type: 'number', description: `Timeout ms. Default ${_shellDefaultTimeoutMs()} (${_shellDefaultTimeoutMs() / 60000} min) when omitted; an explicit value is honored uncapped — long-running commands may set it higher. On timeout the command is MOVED TO BACKGROUND (a task_id you can wait/status/read/cancel) and keeps running instead of being killed; sleep-like commands and MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS opt out (killed with a [timeout] marker). async/background runs with timeout omitted have NO timeout (run until done/cancelled); an explicit timeout is still enforced.` },
                 merge_stderr: { type: 'boolean', description: 'Merge stderr.' },
                 mode: { type: 'string', enum: ['sync', 'async'], description: executionModeSchemaDescription('sync') },
@@ -93,12 +95,12 @@ export const BUILTIN_TOOLS = [
         name: 'task',
         title: 'Background Task Control',
         annotations: { title: 'Background Task Control', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        description: `Manual control for shell async task_id. actions: list/status/read/wait/cancel. ${TOOL_MANUAL_CONTROL_CONTRACT} Not sess_* or agent ids.`,
+        description: `Control a shell async task_id: actions list/status/read/wait/cancel. ${TOOL_MANUAL_CONTROL_CONTRACT} Not sess_* or agent ids.`,
         inputSchema: {
             type: 'object',
             properties: {
                 task_id: { type: 'string', description: 'shell async task_id.' },
-                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Manual action. Avoid polling loops.' },
+                action: { type: 'string', enum: ['list', 'status', 'read', 'wait', 'cancel'], description: 'Action; avoid polling loops.' },
                 timeout_ms: { type: 'number', description: 'Wait timeout ms.' },
                 poll_ms: { type: 'number', description: 'Wait poll ms.' },
             },
@@ -109,7 +111,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: 'Exact text/regex in verified scope (project root counts as verified — unscoped search needs no find). Only a guessed path fragment → find first, same turn. No path "." + guessed src/**. Broad: files_with_matches/count; narrow: content_with_context.',
+        description: 'Quoted/non-identifier literal or regex→grep. Search in verified scope (project root counts as verified); guessed path fragment → find first. Omitted output_mode and content_with_context are contextual; a nonzero content_with_context result resolves that search concept—act directly, without regex tweaks, narrowing or re-search. Choose files_with_matches/count for existence; Only zero/error results may change tokens or scope. No path "." + guessed src/**.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -118,14 +120,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Text/regex. Array = variants in one call.',
+                    description: 'Text/regex. Array = variants in one call; pattern[] batches tokens. path[] batches verified scopes only; file/span reads use read path[] regions.',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified file/dir, or project root; guessed → find first.',
+                    description: 'Verified file/dir or project root; guessed → find first.',
                 },
                 glob: {
                     anyOf: [
@@ -134,21 +136,24 @@ export const BUILTIN_TOOLS = [
                     ],
                     description: 'Glob filter; no guessed src/** under path ".".',
                 },
-                output_mode: { type: 'string', enum: ['content_with_context', 'content', 'files_with_matches', 'count'], description: 'Broad: files_with_matches/count; narrow: content_with_context.' },
+                output_mode: { type: 'string', enum: ['content_with_context', 'files_with_matches', 'count'], description: 'Omitted/contextual content; content_with_context; files_with_matches/count are existence modes. Legacy content is runtime-compatible, not public.' },
                 head_limit: { type: 'number', minimum: 0, description: 'Max results.' },
                 offset: { type: 'number', minimum: 0, description: 'Skip results for paging.' },
                 '-A': { type: 'number', minimum: 0, description: 'Lines after each match.' },
                 '-B': { type: 'number', minimum: 0, description: 'Lines before each match.' },
                 '-C': { type: 'number', minimum: 0, description: 'Lines before/after each match.' },
             },
-            required: [],
+            anyOf: [
+                { required: ['pattern'] },
+                { required: ['glob'] },
+            ],
         },
     },
     {
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Exact glob from verified roots (project root is verified). Guessed root/name → find first, same turn. No path "." + guessed src/**. Batch arrays.',
+        description: 'Exact glob from verified roots (project root is verified); guessed root/name → find first. Array-first: batch related pattern[]/path[]. No path "." + guessed src/**.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -157,14 +162,14 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Exact glob pattern(s). Batch related patterns as pattern[] in one call.',
+                    description: 'Exact glob pattern(s); batch related pattern[].',
                 },
                 path: {
                     anyOf: [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified base dir(s) or project root; guessed → find first. Batch path[].',
+                    description: 'Verified base dir(s)/project root; guessed → find first; batch path[].',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip entries.' },
@@ -176,7 +181,7 @@ export const BUILTIN_TOOLS = [
         name: 'find',
         title: 'Mixdog Find Files',
         annotations: { title: 'Mixdog Find Files', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Partial path/name lookup incl dot dirs; verify roots before grep/glob. Batch query[].',
+        description: 'Partial path/name lookup only for unknown partial paths/names (including dot dirs); verify roots before grep/glob. Not for the project root or already-verified roots. Output paths are verified downstream. Array-first: batch query[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -185,7 +190,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Partial path/name words (not file contents), or query[] to batch lookups in one call.',
+                    description: 'Partial path/name words, not contents; query[] batches lookups.',
                 },
                 path: { type: 'string', description: 'Base directory.' },
                 head_limit: { type: 'number', description: 'Max paths.' },
@@ -197,7 +202,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List verified directories (project root included). Guessed dir → find first. Batch dirs as path[].',
+        description: 'List verified directories (project root included); Guessed dir → find first. Array-first: batch independent dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {
@@ -206,7 +211,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified directory, or path[] to list several directories in one call.',
+                    description: 'Verified directory; path[] batches directories.',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip N entries for paging.' },

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

@@ -19,10 +19,13 @@ export const FS_REACHABILITY_DEADLINE_MS = 5000;
 // error). Reject with EFSUNREACHABLE only when the stat itself exceeds the
 // deadline, which is the dead-mount / hung-FS signature.
 export async function assertPathReachable(path, deadlineMs = FS_REACHABILITY_DEADLINE_MS) {
-    if (typeof path !== 'string' || path.length === 0) return;
+    if (typeof path !== 'string' || path.length === 0) return null;
     const ms = Number(deadlineMs) > 0 ? Number(deadlineMs) : FS_REACHABILITY_DEADLINE_MS;
     let timer = null;
-    const probe = stat(path).then(() => true, () => true); // any answer = reachable
+    // Resolve to the Stats on success so a caller can seed its stat cache and
+    // avoid an immediate redundant synchronous re-stat of the same path; a
+    // clean FS rejection (ENOENT/EACCES) resolves to null (still "reachable").
+    const probe = stat(path).then((s) => s, () => null);
     const deadline = new Promise((resolve) => {
         timer = setTimeout(() => resolve('TIMEOUT'), ms);
     });
@@ -37,6 +40,7 @@ export async function assertPathReachable(path, deadlineMs = FS_REACHABILITY_DEA
         err.code = 'EFSUNREACHABLE';
         throw err;
     }
+    return result; // Stats on success, null on a clean FS rejection
 }
 
 // Batch variant: reject if ANY path is unreachable. Runs probes concurrently so