mixdog 0.9.174 → 1.0.0

package/src/runtime/agent/orchestrator/session/context-identity-writer.mjs

@@ -0,0 +1,162 @@
+import { isWhitespace } from './token-estimate-floors.mjs';
+
+// --- Identity serialization -------------------------------------------------
+//
+// A message's identity is hashed as the UTF-8 bytes of JSON.stringify(identity)
+// followed by '\0'. The bytes are produced here directly into a reused scratch
+// buffer: the transcript text inside an identity is escaped (and, for the
+// shape identity, normalized) on the fly instead of first building the
+// escaped JSON, the placeholder-stripped copy and the whitespace-collapsed
+// copy of every message. The byte stream — and so every digest — is exactly
+// the one JSON.stringify produces.
+const IDENTITY_SCRATCH = Buffer.allocUnsafe(1 << 16);
+const HEX_DIGITS = '0123456789abcdef';
+// \b \t \n \f \r: the control characters JSON.stringify escapes by letter.
+const SHORT_ESCAPES = new Uint8Array(32);
+SHORT_ESCAPES[0x08] = 0x62;
+SHORT_ESCAPES[0x09] = 0x74;
+SHORT_ESCAPES[0x0a] = 0x6e;
+SHORT_ESCAPES[0x0c] = 0x66;
+SHORT_ESCAPES[0x0d] = 0x72;
+let identityPos = 0;
+let identityHash = null;
+
+function flushIdentity() {
+  if (identityPos) identityHash.update(IDENTITY_SCRATCH.subarray(0, identityPos));
+  identityPos = 0;
+}
+
+function reserveIdentity(bytes) {
+  if (identityPos + bytes > IDENTITY_SCRATCH.length) flushIdentity();
+}
+
+function putUnicodeEscape(code) {
+  const s = IDENTITY_SCRATCH;
+  s[identityPos++] = 0x5c;
+  s[identityPos++] = 0x75;
+  s[identityPos++] = HEX_DIGITS.charCodeAt((code >> 12) & 15);
+  s[identityPos++] = HEX_DIGITS.charCodeAt((code >> 8) & 15);
+  s[identityPos++] = HEX_DIGITS.charCodeAt((code >> 4) & 15);
+  s[identityPos++] = HEX_DIGITS.charCodeAt(code & 15);
+}
+
+// Writes the code unit at `index` of `text` (a whole surrogate pair when one
+// starts there) as UTF-8, JSON-escaped when `jsonEscape`; returns the next index.
+function putCodeUnit(text, index, jsonEscape) {
+  reserveIdentity(6);
+  const s = IDENTITY_SCRATCH;
+  const c = text.charCodeAt(index);
+  if (c < 0x80) {
+    if (!jsonEscape || (c >= 0x20 && c !== 0x22 && c !== 0x5c)) {
+      s[identityPos++] = c;
+    } else if (c === 0x22 || c === 0x5c) {
+      s[identityPos++] = 0x5c;
+      s[identityPos++] = c;
+    } else if (SHORT_ESCAPES[c]) {
+      s[identityPos++] = 0x5c;
+      s[identityPos++] = SHORT_ESCAPES[c];
+    } else {
+      putUnicodeEscape(c);
+    }
+    return index + 1;
+  }
+  if (c < 0x800) {
+    s[identityPos++] = 0xc0 | (c >> 6);
+    s[identityPos++] = 0x80 | (c & 0x3f);
+    return index + 1;
+  }
+  if (c >= 0xd800 && c <= 0xdfff) {
+    const next = c <= 0xdbff && index + 1 < text.length ? text.charCodeAt(index + 1) : 0;
+    if (next >= 0xdc00 && next <= 0xdfff) {
+      const point = (c - 0xd800) * 0x400 + (next - 0xdc00) + 0x10000;
+      s[identityPos++] = 0xf0 | (point >> 18);
+      s[identityPos++] = 0x80 | ((point >> 12) & 0x3f);
+      s[identityPos++] = 0x80 | ((point >> 6) & 0x3f);
+      s[identityPos++] = 0x80 | (point & 0x3f);
+      return index + 2;
+    }
+    // A lone surrogate: JSON.stringify escapes it (raw JSON never has one).
+    putUnicodeEscape(c);
+    return index + 1;
+  }
+  s[identityPos++] = 0xe0 | (c >> 12);
+  s[identityPos++] = 0x80 | ((c >> 6) & 0x3f);
+  s[identityPos++] = 0x80 | (c & 0x3f);
+  return index + 1;
+}
+
+export function putRaw(text) {
+  for (let index = 0; index < text.length; ) index = putCodeUnit(text, index, false);
+}
+
+export function putJsonString(text) {
+  putRaw('"');
+  for (let index = 0; index < text.length; ) index = putCodeUnit(text, index, true);
+  putRaw('"');
+}
+
+// One element of an identity array (strings escaped here; the other values
+// are small plain data and serialize through JSON.stringify).
+export function putJsonElement(value) {
+  if (typeof value === 'string') putJsonString(value);
+  else putRaw(JSON.stringify(value) ?? 'null');
+}
+
+const STORED_MEDIA_PLACEHOLDER_PREFIXES = ['[Image omitted from stored history', '[File omitted from stored history'];
+
+// JSON.stringify of
+//   text.replace(/\[(?:Image|File) omitted from stored history[^\]]*\]/g, ' ')
+//       .replace(/\s+/g, ' ').trim()
+// written in one pass; returns how many placeholders were replaced.
+export function putShapeText(text) {
+  putRaw('"');
+  let placeholders = 0;
+  let emitted = false;
+  let pendingSpace = false;
+  let closable = true;
+  for (let index = 0; index < text.length; ) {
+    const c = text.charCodeAt(index);
+    if (c === 0x5b && closable) {
+      let prefix = null;
+      for (const candidate of STORED_MEDIA_PLACEHOLDER_PREFIXES) {
+        if (text.startsWith(candidate, index)) prefix = candidate;
+      }
+      if (prefix) {
+        const close = text.indexOf(']', index + prefix.length);
+        // No `]` after this one means no later placeholder can close either.
+        if (close < 0) {
+          closable = false;
+        } else {
+          placeholders += 1;
+          pendingSpace = emitted;
+          index = close + 1;
+          continue;
+        }
+      }
+    }
+    if (isWhitespace(c)) {
+      pendingSpace = emitted;
+      index += 1;
+      continue;
+    }
+    if (pendingSpace) {
+      putRaw(' ');
+      pendingSpace = false;
+    }
+    index = putCodeUnit(text, index, true);
+    emitted = true;
+  }
+  putRaw('"');
+  return placeholders;
+}
+
+export function beginIdentity(hash) {
+  identityHash = hash;
+  identityPos = 0;
+}
+
+export function endIdentity() {
+  putRaw('\0');
+  flushIdentity();
+  identityHash = null;
+}

package/src/runtime/agent/orchestrator/session/context-tool-pairs.mjs

@@ -67,9 +67,9 @@ export function sanitizeToolPairs(messages) {
     const m = messages[idx];
     // Tool results are only ever placed by the assistant turn that called
     // them; a loose one (orphaned, duplicated or misplaced) is dropped.
-    if (m.role === 'tool') continue;
+    if (m?.role === 'tool') continue;
     result.push(m);
-    if (m.role !== 'assistant') continue;
+    if (m?.role !== 'assistant') continue;
     for (const callId of collectAssistantToolCallIds(m)) {
       if (placedToolIds.has(callId)) continue;
       const existing = pickToolResultForAssistant(messages, idx, callId);

package/src/runtime/agent/orchestrator/session/context-tool-schema.mjs

@@ -0,0 +1,87 @@
+// Tool/function schema fingerprint and token cost: the request-side half of the
+// context estimate (schemas travel beside `messages`, not inside them).
+import { createHash } from 'node:crypto';
+import { estimateTokens } from './token-estimate.mjs';
+import {
+  isFinalizedProviderRequestTools,
+  providerNativeToolPrefixCount,
+} from '../runtime-core/provider-request-tools.mjs';
+
+const toolSchemaAnalysisMemo = new WeakMap();
+
+function isDeferredToolSchema(tool) {
+  return tool?.deferLoading === true || tool?.defer_loading === true;
+}
+
+function serializeToolSchemas(tools, { excludeDeferred = false } = {}) {
+  const list = Array.isArray(tools) ? tools : [];
+  const nativePrefixCount = providerNativeToolPrefixCount(list);
+  try {
+    const wire = [];
+    list.forEach((tool, index) => {
+      const deferred = isDeferredToolSchema(tool);
+      if (excludeDeferred && deferred) return;
+      if (index < nativePrefixCount) {
+        wire.push(tool);
+        return;
+      }
+      const wireTool = {
+        name: tool?.name,
+        description: tool?.description,
+        input_schema: tool?.inputSchema ?? tool?.input_schema ?? tool?.parameters ?? tool?.schema,
+      };
+      if (deferred) wireTool.defer_loading = true;
+      wire.push(wireTool);
+    });
+    return JSON.stringify(wire);
+  } catch {
+    return list
+      .filter((tool) => !(excludeDeferred && isDeferredToolSchema(tool)))
+      .map((t) => String(t?.name ?? ''))
+      .join('');
+  }
+}
+
+export function toolSchemaSignature(tools) {
+  return analyzeToolSchemas(tools).signature;
+}
+
+function analyzeToolSchemas(tools) {
+  const list = Array.isArray(tools) ? tools : [];
+  const cached = Array.isArray(tools) ? toolSchemaAnalysisMemo.get(tools) : null;
+  if (cached && isFinalizedProviderRequestTools(tools)) return cached;
+  const text = serializeToolSchemas(list);
+  const signature = createHash('sha256').update(text).digest('hex');
+  if (cached && cached.signature === signature) return cached;
+  // defer_loading schemas ride the wire but the API excludes them from
+  // context-token calculation and prompt-cache keys, so metering them at
+  // full weight inflated the request reserve. The SIGNATURE keeps hashing
+  // the full serialization (a deferred tool joining/leaving must still
+  // re-fingerprint the surface); only the token cost drops deferred entries.
+  const meterText = list.some(isDeferredToolSchema) ? serializeToolSchemas(list, { excludeDeferred: true }) : text;
+  const analysis = { signature, tokens: estimateTokens(meterText) };
+  if (Array.isArray(tools)) toolSchemaAnalysisMemo.set(tools, analysis);
+  return analysis;
+}
+
+/**
+ * Estimate the token cost of the tool/function schemas a provider appends to
+ * the request body. These are NOT part of `messages` (they're a separate
+ * argument to provider.send), so estimateMessagesTokens() ignores them
+ * entirely — a transcript that "fits" by message tokens can still overflow
+ * once N tool schemas are serialized into the same request. Best-effort
+ * chars/4 over the JSON-serialized definitions.
+ */
+export function estimateToolSchemaTokens(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) return 0;
+  return analyzeToolSchemas(tools).tokens;
+}
+
+/**
+ * Total request-side bytes the caller should reserve out of the context window
+ * before compaction. Only serialized tool schemas are counted; providers do
+ * not expose a stable framing cost, so no synthetic fixed allowance is added.
+ */
+export function estimateRequestReserveTokens(tools) {
+  return estimateToolSchemaTokens(tools);
+}

package/src/runtime/agent/orchestrator/session/context-utils.mjs

@@ -1,13 +1,10 @@
 import { createHash } from 'node:crypto';
 import { estimateTokens } from './token-estimate.mjs';
-import { isWhitespace } from './token-estimate-floors.mjs';
+import { beginIdentity, endIdentity, putJsonElement, putJsonString, putRaw, putShapeText } from './context-identity-writer.mjs';
 import { positiveInt } from '../../../shared/numbers.mjs';
 import { hasPlainPrototype } from '../../../shared/object.mjs';
 import { createContextFingerprinter } from './context-fingerprint.mjs';
-import {
-  isFinalizedProviderRequestTools,
-  providerNativeToolPrefixCount,
-} from '../../../../session-runtime/provider-request-tools.mjs';
+import { estimateRequestReserveTokens } from './context-tool-schema.mjs';
 import {
   contentFileDescriptors,
   contentImageDescriptors,
@@ -96,6 +93,7 @@ export function providerTokenCalibration(provider) {
 const IMAGE_TOKEN_ALLOWANCE = 1_568;
 
 export { estimateTokens };
+export { estimateRequestReserveTokens, estimateToolSchemaTokens, toolSchemaSignature } from './context-tool-schema.mjs';
 
 // Opaque replay payloads (Anthropic thinking signatures, OpenAI encrypted
 // reasoning blobs, redacted data) are long base64-ish strings that ARE billed
@@ -931,167 +929,6 @@ function pruneSignatureStates(chain) {
   }
 }
 
-// --- Identity serialization -------------------------------------------------
-//
-// A message's identity is hashed as the UTF-8 bytes of JSON.stringify(identity)
-// followed by '\0'. The bytes are produced here directly into a reused scratch
-// buffer: the transcript text inside an identity is escaped (and, for the
-// shape identity, normalized) on the fly instead of first building the
-// escaped JSON, the placeholder-stripped copy and the whitespace-collapsed
-// copy of every message. The byte stream — and so every digest — is exactly
-// the one JSON.stringify produces.
-const IDENTITY_SCRATCH = Buffer.allocUnsafe(1 << 16);
-const HEX_DIGITS = '0123456789abcdef';
-// \b \t \n \f \r: the control characters JSON.stringify escapes by letter.
-const SHORT_ESCAPES = new Uint8Array(32);
-SHORT_ESCAPES[0x08] = 0x62;
-SHORT_ESCAPES[0x09] = 0x74;
-SHORT_ESCAPES[0x0a] = 0x6e;
-SHORT_ESCAPES[0x0c] = 0x66;
-SHORT_ESCAPES[0x0d] = 0x72;
-let identityPos = 0;
-let identityHash = null;
-
-function flushIdentity() {
-  if (identityPos) identityHash.update(IDENTITY_SCRATCH.subarray(0, identityPos));
-  identityPos = 0;
-}
-
-function reserveIdentity(bytes) {
-  if (identityPos + bytes > IDENTITY_SCRATCH.length) flushIdentity();
-}
-
-function putUnicodeEscape(code) {
-  const s = IDENTITY_SCRATCH;
-  s[identityPos++] = 0x5c;
-  s[identityPos++] = 0x75;
-  s[identityPos++] = HEX_DIGITS.charCodeAt((code >> 12) & 15);
-  s[identityPos++] = HEX_DIGITS.charCodeAt((code >> 8) & 15);
-  s[identityPos++] = HEX_DIGITS.charCodeAt((code >> 4) & 15);
-  s[identityPos++] = HEX_DIGITS.charCodeAt(code & 15);
-}
-
-// Writes the code unit at `index` of `text` (a whole surrogate pair when one
-// starts there) as UTF-8, JSON-escaped when `escape`; returns the next index.
-function putCodeUnit(text, index, escape) {
-  reserveIdentity(6);
-  const s = IDENTITY_SCRATCH;
-  const c = text.charCodeAt(index);
-  if (c < 0x80) {
-    if (!escape || (c >= 0x20 && c !== 0x22 && c !== 0x5c)) {
-      s[identityPos++] = c;
-    } else if (c === 0x22 || c === 0x5c) {
-      s[identityPos++] = 0x5c;
-      s[identityPos++] = c;
-    } else if (SHORT_ESCAPES[c]) {
-      s[identityPos++] = 0x5c;
-      s[identityPos++] = SHORT_ESCAPES[c];
-    } else {
-      putUnicodeEscape(c);
-    }
-    return index + 1;
-  }
-  if (c < 0x800) {
-    s[identityPos++] = 0xc0 | (c >> 6);
-    s[identityPos++] = 0x80 | (c & 0x3f);
-    return index + 1;
-  }
-  if (c >= 0xd800 && c <= 0xdfff) {
-    const next = c <= 0xdbff && index + 1 < text.length ? text.charCodeAt(index + 1) : 0;
-    if (next >= 0xdc00 && next <= 0xdfff) {
-      const point = (c - 0xd800) * 0x400 + (next - 0xdc00) + 0x10000;
-      s[identityPos++] = 0xf0 | (point >> 18);
-      s[identityPos++] = 0x80 | ((point >> 12) & 0x3f);
-      s[identityPos++] = 0x80 | ((point >> 6) & 0x3f);
-      s[identityPos++] = 0x80 | (point & 0x3f);
-      return index + 2;
-    }
-    // A lone surrogate: JSON.stringify escapes it (raw JSON never has one).
-    putUnicodeEscape(c);
-    return index + 1;
-  }
-  s[identityPos++] = 0xe0 | (c >> 12);
-  s[identityPos++] = 0x80 | ((c >> 6) & 0x3f);
-  s[identityPos++] = 0x80 | (c & 0x3f);
-  return index + 1;
-}
-
-function putRaw(text) {
-  for (let index = 0; index < text.length; ) index = putCodeUnit(text, index, false);
-}
-
-function putJsonString(text) {
-  putRaw('"');
-  for (let index = 0; index < text.length; ) index = putCodeUnit(text, index, true);
-  putRaw('"');
-}
-
-// One element of an identity array (strings escaped here; the other values
-// are small plain data and serialize through JSON.stringify).
-function putJsonElement(value) {
-  if (typeof value === 'string') putJsonString(value);
-  else putRaw(JSON.stringify(value) ?? 'null');
-}
-
-const STORED_MEDIA_PLACEHOLDER_PREFIXES = ['[Image omitted from stored history', '[File omitted from stored history'];
-
-// JSON.stringify of
-//   text.replace(/\[(?:Image|File) omitted from stored history[^\]]*\]/g, ' ')
-//       .replace(/\s+/g, ' ').trim()
-// written in one pass; returns how many placeholders were replaced.
-function putShapeText(text) {
-  putRaw('"');
-  let placeholders = 0;
-  let emitted = false;
-  let pendingSpace = false;
-  let closable = true;
-  for (let index = 0; index < text.length; ) {
-    const c = text.charCodeAt(index);
-    if (c === 0x5b && closable) {
-      let prefix = null;
-      for (const candidate of STORED_MEDIA_PLACEHOLDER_PREFIXES) {
-        if (text.startsWith(candidate, index)) prefix = candidate;
-      }
-      if (prefix) {
-        const close = text.indexOf(']', index + prefix.length);
-        // No `]` after this one means no later placeholder can close either.
-        if (close < 0) {
-          closable = false;
-        } else {
-          placeholders += 1;
-          pendingSpace = emitted;
-          index = close + 1;
-          continue;
-        }
-      }
-    }
-    if (isWhitespace(c)) {
-      pendingSpace = emitted;
-      index += 1;
-      continue;
-    }
-    if (pendingSpace) {
-      putRaw(' ');
-      pendingSpace = false;
-    }
-    index = putCodeUnit(text, index, true);
-    emitted = true;
-  }
-  putRaw('"');
-  return placeholders;
-}
-
-function beginIdentity(hash) {
-  identityHash = hash;
-  identityPos = 0;
-}
-
-function endIdentity() {
-  putRaw('\0');
-  flushIdentity();
-  identityHash = null;
-}
-
 // JSON.stringify([role, toolCallId, estimateText, imageAllowance, images]).
 // Every value is taken before anything is written, so a throwing projection
 // leaves `hash` untouched.
@@ -1431,85 +1268,6 @@ export function contextMessagesShapeSignature(messages, count = messages?.length
   return memoizedTranscriptSignature(messages, count, 'shape', hashShapeIdentity);
 }
 
-const toolSchemaAnalysisMemo = new WeakMap();
-
-function isDeferredToolSchema(tool) {
-  return tool?.deferLoading === true || tool?.defer_loading === true;
-}
-
-function serializeToolSchemas(tools, { excludeDeferred = false } = {}) {
-  const list = Array.isArray(tools) ? tools : [];
-  const nativePrefixCount = providerNativeToolPrefixCount(list);
-  try {
-    const wire = [];
-    list.forEach((tool, index) => {
-      const deferred = isDeferredToolSchema(tool);
-      if (excludeDeferred && deferred) return;
-      if (index < nativePrefixCount) {
-        wire.push(tool);
-        return;
-      }
-      const wireTool = {
-        name: tool?.name,
-        description: tool?.description,
-        input_schema: tool?.inputSchema ?? tool?.input_schema ?? tool?.parameters ?? tool?.schema,
-      };
-      if (deferred) wireTool.defer_loading = true;
-      wire.push(wireTool);
-    });
-    return JSON.stringify(wire);
-  } catch {
-    return list
-      .filter((tool) => !(excludeDeferred && isDeferredToolSchema(tool)))
-      .map((t) => String(t?.name ?? ''))
-      .join('');
-  }
-}
-
-export function toolSchemaSignature(tools) {
-  return analyzeToolSchemas(tools).signature;
-}
-
-function analyzeToolSchemas(tools) {
-  const list = Array.isArray(tools) ? tools : [];
-  const cached = Array.isArray(tools) ? toolSchemaAnalysisMemo.get(tools) : null;
-  if (cached && isFinalizedProviderRequestTools(tools)) return cached;
-  const text = serializeToolSchemas(list);
-  const signature = createHash('sha256').update(text).digest('hex');
-  if (cached && cached.signature === signature) return cached;
-  // defer_loading schemas ride the wire but the API excludes them from
-  // context-token calculation and prompt-cache keys, so metering them at
-  // full weight inflated the request reserve. The SIGNATURE keeps hashing
-  // the full serialization (a deferred tool joining/leaving must still
-  // re-fingerprint the surface); only the token cost drops deferred entries.
-  const meterText = list.some(isDeferredToolSchema) ? serializeToolSchemas(list, { excludeDeferred: true }) : text;
-  const analysis = { signature, tokens: estimateTokens(meterText) };
-  if (Array.isArray(tools)) toolSchemaAnalysisMemo.set(tools, analysis);
-  return analysis;
-}
-
-/**
- * Estimate the token cost of the tool/function schemas a provider appends to
- * the request body. These are NOT part of `messages` (they're a separate
- * argument to provider.send), so estimateMessagesTokens() ignores them
- * entirely — a transcript that "fits" by message tokens can still overflow
- * once N tool schemas are serialized into the same request. Best-effort
- * chars/4 over the JSON-serialized definitions.
- */
-export function estimateToolSchemaTokens(tools) {
-  if (!Array.isArray(tools) || tools.length === 0) return 0;
-  return analyzeToolSchemas(tools).tokens;
-}
-
-/**
- * Total request-side bytes the caller should reserve out of the context window
- * before compaction. Only serialized tool schemas are counted; providers do
- * not expose a stable framing cost, so no synthetic fixed allowance is added.
- */
-export function estimateRequestReserveTokens(tools) {
-  return estimateToolSchemaTokens(tools);
-}
-
 /**
  * Live/current context numerator SSOT: transcript estimate + request reserve.
  * Provider-reported usage is excluded (secondary metadata only).

package/src/runtime/agent/orchestrator/session/eager-dispatch/admission.mjs

@@ -14,7 +14,7 @@ import {
   _repeatFailureSig,
   _stripMcpPrefix,
 } from '../loop/tool-classify.mjs';
-import { getToolKind, isSingleCallPerTurnTool, isToolCallDedupEligible } from '../loop/tool-helpers.mjs';
+import { isSingleCallPerTurnTool, isToolCallDedupEligible } from '../loop/tool-helpers.mjs';
 import { tryReadCached, tryScopedToolCached } from '../read-dedup.mjs';
 
 export function createEagerAdmission({
@@ -98,8 +98,7 @@ export function createEagerAdmission({
     // body handles it via the invalid-args feedback path.
     if (isInvalidToolArgsMarker(call.arguments)) return null;
     // Authorization precedes cache lookup and dedup, not just IO.
-    const toolKind = getToolKind(call.name, sessionRef?.mcpScopeId);
-    if (preDispatchDenyForSession(sessionRef, call, toolKind) !== null) return null;
+    if (preDispatchDenyForSession(sessionRef, call) !== null) return null;
     const sig = _intraTurnSig(call.name, call.arguments);
     const dedupEligible = isToolCallDedupEligible(call.name, tools);
     if (dedupEligible && _eagerInFlightSigs.has(sig)) return null;

package/src/runtime/agent/orchestrator/session/eager-dispatch/mutation-paths.mjs

@@ -0,0 +1,54 @@
+// Mutation path log for the eager mutation epoch: every epoch advance also
+// records the paths that mutation touched (null = unknown), so an eager read
+// can tell whether a mutation after its dispatch affected its target files.
+import { isAbsolute, normalize, resolve } from 'node:path';
+import { extractTouchedPathsFromPatch } from '../cache/read-cache.mjs';
+import { _stripMcpPrefix } from '../loop/tool-classify.mjs';
+
+function absPath(value, base) {
+  const abs = isAbsolute(value) ? normalize(value) : resolve(base || process.cwd(), value);
+  return process.platform === 'win32' ? abs.toLowerCase() : abs;
+}
+
+function argPaths(args) {
+  const raw = args?.file_path ?? args?.path;
+  // Read windows arrive as { file_path, offset, limit } entries.
+  const list = (Array.isArray(raw) ? raw : [raw]).map((p) => (p && typeof p === 'object' ? p.file_path : p));
+  return list.every((p) => typeof p === 'string' && p.length > 0) ? list : null;
+}
+
+// Absolute paths a mutation call touches, or null when unknown.
+function mutationPaths(call, cwd) {
+  const name = _stripMcpPrefix(call.name);
+  const args = call.arguments;
+  if (name === 'edit') {
+    const paths = argPaths(args);
+    return paths && paths.map((p) => absPath(p, cwd));
+  }
+  if (name === 'apply_patch') {
+    const patch = typeof args === 'string' ? args : args?.patch;
+    const touched = extractTouchedPathsFromPatch(patch);
+    if (touched.length === 0) return null;
+    const base = typeof args?.base_path === 'string' && args.base_path ? absPath(args.base_path, cwd) : cwd;
+    return touched.map((p) => absPath(p, base));
+  }
+  return null;
+}
+
+export function recordMutation(epoch, call, cwd) {
+  const log = (epoch.log ??= []);
+  log[epoch.mutation] = mutationPaths(call, cwd);
+  epoch.mutation += 1;
+}
+
+// True when a mutation recorded at or after `sinceEpoch` may have changed
+// the read's targets (unknown mutation paths, glob or unparseable targets).
+export function mutationAffectsRead(epoch, sinceEpoch, call, cwd) {
+  const targets = argPaths(call.arguments);
+  const after = [];
+  for (let i = sinceEpoch; i < epoch.mutation; i += 1) after.push(epoch.log?.[i] ?? null);
+  if (after.length === 0) return false;
+  if (!targets || targets.some((p) => /[*?[\]{}]/.test(p))) return true;
+  const abs = new Set(targets.map((p) => absPath(p, cwd)));
+  return after.some((paths) => paths === null || paths.some((p) => abs.has(p)));
+}

package/src/runtime/agent/orchestrator/session/eager-dispatch.mjs

@@ -25,7 +25,7 @@ export function createEagerDispatcher({
   executeToolFn = executeTool,
 }) {
   const pending = new Map();
-  const epoch = { mutation: 0 };
+  const epoch = { mutation: 0, log: [] };
   const admission = createEagerAdmission({
     tools,
     cwd,

package/src/runtime/agent/orchestrator/session/lifecycle-scan.mjs

@@ -62,7 +62,7 @@
 // Single authoritative rejection marker: ambiguous OR malformed OR
 // wrong-typed. Frozen and deliberately carrying no `id`/`closed`/`generation`
 // so a lenient consumer that forgets the check still reads nothing usable.
-export const LIFECYCLE_SCAN_CONFLICT = Object.freeze({ conflict: 'unreadable' });
+const LIFECYCLE_SCAN_CONFLICT = Object.freeze({ conflict: 'unreadable' });
 
 /** True for the rejection marker (and for anything that isn't a record). */
 export function isLifecycleUnreadable(result) {
@@ -207,18 +207,3 @@ export function readTopLevelLifecycleRecord(raw) {
   }
   return record;
 }
-
-/**
- * Lifecycle fields only (no parsed document) for callers that consult nothing
- * else. Same two outcomes: the fields present at top level, or
- * LIFECYCLE_SCAN_CONFLICT.
- */
-export function scanTopLevelLifecycle(raw) {
-  const record = readTopLevelLifecycleRecord(raw);
-  if (isLifecycleUnreadable(record)) return LIFECYCLE_SCAN_CONFLICT;
-  const out = {};
-  if (record.id !== undefined) out.id = record.id;
-  if (record.closed !== undefined) out.closed = record.closed;
-  if (record.generation !== undefined) out.generation = record.generation;
-  return out;
-}

package/src/runtime/agent/orchestrator/session/loop/arg-schema-coerce.mjs

@@ -5,8 +5,8 @@
 // parsed and kept only if the parsed value fits a declared type; anything else
 // stays untouched so real string arguments and malformed text still reach the
 // tool's own validation.
-import { clean } from '../../../../../session-runtime/session-text.mjs';
-import { deferredCatalogUnion } from '../../../../../session-runtime/tool-catalog.mjs';
+import { clean } from '../../runtime-core/session-text.mjs';
+import { deferredCatalogUnion } from '../../runtime-core/tool-catalog.mjs';
 import { getInternalTools } from '../../internal-tools.mjs';
 
 const STRUCTURAL_TYPES = new Set(['object', 'array', 'number', 'integer', 'boolean', 'null']);