mixdog 1.0.12 → 1.1.0

package/src/runtime/agent/orchestrator/runtime-core/session-route-policy.mjs

@@ -19,6 +19,22 @@ export function sessionHasRouteHistory(session) {
   return hasRouteHistoryMessage(session?.messages) || hasRouteHistoryMessage(session?.liveTurnMessages);
 }
 
+// Whether a model change must leave the current conversation on its model:
+// a model reply or a compaction summary ties it to its provider cache and
+// replay state, and a first turn in flight owns its model. Prompts that were
+// all refused before any reply leave nothing to protect.
+export function sessionRouteCommitted(session) {
+  const messages = Array.isArray(session?.messages) ? session.messages : [];
+  return (
+    hasRouteHistoryMessage(session?.liveTurnMessages) ||
+    messages.some(
+      (message) =>
+        message?.role === 'assistant' ||
+        (message?.role === 'user' && typeof message.content === 'string' && message.content.startsWith(SUMMARY_PREFIX))
+    )
+  );
+}
+
 export function sessionUsesRoute(session, route) {
   return !!session && session.provider === route?.provider && session.model === route?.model;
 }

package/src/runtime/agent/orchestrator/runtime-core/tool-catalog.mjs

@@ -305,6 +305,8 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
   }
   const catalog = sortedCatalogByMeasuredUsage([...byName.values()]);
   const defaultNames = defaultDeferredToolNames(catalog, mode);
+  // Solo keeps `agent` in the deferred pool: loadable on request, never eager.
+  if (session.orchestrationMode === 'none') defaultNames.delete('agent');
   const storedNames = providerMode === 'native' ? [] : storedDeferredToolNames(session);
   const fixedSurface = FIXED_SURFACE_MODES.has(providerMode);
   let selectedNames = fixedSurface

package/src/runtime/agent/orchestrator/runtime-core/tool-defs.mjs

@@ -144,8 +144,8 @@ export function collectStandaloneToolDefs({
   return {
     standaloneTools,
     internalToolDefs: [...standaloneTools, ...webSearchRuntimeTools.filter((tool) => tool?.public === false)],
-    // Workflow-aware model surface: a pack that declares an EMPTY agents list
-    // (Solo) must not advertise the agent tool at all — the model calling a
+    // Workflow-aware model surface: a session with no delegatable agents
+    // must not advertise the agent tool at all — the model calling a
     // schema-visible tool that policy always rejects is a guaranteed error turn
     // (user-reported in Solo). Names derive from the live agent tool defs.
     agentToolNames: new Set(agentTools.map((tool) => String(tool?.name || '')).filter(Boolean)),

package/src/runtime/agent/orchestrator/runtime-core/workflow/context.mjs

@@ -6,7 +6,7 @@ import { orchestrationInstructions } from '../orchestration.mjs';
 import { DEFAULT_WORKFLOW_ID, normalizeWorkflowId } from '../workflow-ids.mjs';
 
 export function createWorkflowContext({ packs, agents }) {
-  function workflowSummary(pack, { hasAgents = true, orchestrationMode = 'none' } = {}) {
+  function workflowSummary(pack, { hasAgents = true } = {}) {
     const id = normalizeWorkflowId(pack?.id, DEFAULT_WORKFLOW_ID);
     return {
       id,
@@ -14,7 +14,8 @@ export function createWorkflowContext({ packs, agents }) {
       description: clean(pack?.description),
       source: clean(pack?.source),
       // Effective session capability, not an editable workflow property.
-      delegatesAgents: orchestrationMode !== 'none' && hasAgents !== false,
+      // Solo keeps the agent tool deferred for explicit user requests.
+      delegatesAgents: hasAgents !== false,
     };
   }
 
@@ -23,7 +24,6 @@ export function createWorkflowContext({ packs, agents }) {
   function activeWorkflowSummary(config, dir) {
     return workflowSummary(packs.sharedWorkflowPack(dir, packs.activeWorkflowId(config)), {
       hasAgents: agents.delegatableAgentIds(config, dir).length > 0,
-      orchestrationMode: configuredOrchestrationMode(config),
     });
   }
 
@@ -44,10 +44,11 @@ export function createWorkflowContext({ packs, agents }) {
   }
 
   function orchestrationContextBlock(config, dir) {
-    const instructions = orchestrationInstructions(configuredOrchestrationMode(config));
-    if (!instructions) return '';
-    const lines = [instructions];
+    const mode = configuredOrchestrationMode(config);
     const agentIds = agents.delegatableAgentIds(config, dir);
+    // Solo without agents has nothing to delegate to on request either.
+    if (mode === 'none' && !agentIds.length) return '';
+    const lines = [orchestrationInstructions(mode)];
     const agentBlocks = agentIds.map((id) => agents.loadAgentDefinition(dir, id)).filter(Boolean);
     if (agentBlocks.length) {
       lines.push('# Available Agents');
@@ -74,7 +75,6 @@ export function createWorkflowContext({ packs, agents }) {
     return {
       summary: workflowSummary(pack, {
         hasAgents: agents.delegatableAgentIds(config, dir).length > 0,
-        orchestrationMode,
       }),
       orchestrationMode,
       // Pack block alone: agent-owned sessions never get the Lead-only

package/src/runtime/agent/orchestrator/runtime-core/workflow.mjs

@@ -187,12 +187,18 @@ export function normalizeWorkflowRoute(routeLike, fallback = {}) {
   const effort = normalizeEffortInput(routeLike?.effort ?? fallback.effort);
   const fast = routeLike?.fast ?? fallback.fast;
   const modelParameters = routeLike?.modelParameters ?? fallback.modelParameters;
+  const requestedPercent = Number(routeLike?.contextPercent ?? fallback.contextPercent);
+  const contextPercent =
+    Number.isFinite(requestedPercent) && requestedPercent >= 10 && requestedPercent <= 100
+      ? Math.round(requestedPercent / 10) * 10
+      : null;
   return {
     provider,
     model,
     ...(effort ? { effort } : {}),
     ...(typeof fast === 'boolean' ? { fast } : {}),
     ...(modelParameters && typeof modelParameters === 'object' ? { modelParameters: { ...modelParameters } } : {}),
+    ...(contextPercent ? { contextPercent } : {}),
   };
 }
 

package/src/runtime/agent/orchestrator/session/loop/step-auto-effort.mjs

@@ -8,9 +8,13 @@
  * later request rebuilds the same history and the prompt cache keeps hitting.
  * A judge that is missing, slow or failing leaves the step at the effort in
  * force (the turn's or the previous step's).
+ * A custom route (snapshot mode 'custom') has no mid-conversation update: the
+ * judged effort, snapped onto the model's levels, becomes the effort of the
+ * turn's following requests.
  */
 import { resolveAutoEffort } from '../../providers/auto-effort.mjs';
-import { stepEffortConfiguration } from '../../providers/effort-configuration.mjs';
+import { resolveCustomReasoning } from '../../providers/custom-reasoning.mjs';
+import { autoEffortModel, stepEffortConfiguration } from '../../providers/effort-configuration.mjs';
 import { effortOptionsFor } from '../../runtime-core/effort.mjs';
 import { judgeTurn, recordEffortDecision } from '../../../../effort-judge/judge-client.mjs';
 import { stepResultWindow } from '../../../../effort-judge/judge-input.mjs';
@@ -68,14 +72,22 @@ export async function markStepEffort(state, assistantTurnMsg) {
     },
   });
   // `atStep` numbers the tool-result step; `step` in a resolved decision is the ladder move.
-  const record = { at: new Date().toISOString(), sessionId: state.sessionId, provider, model, mode: 'on', atStep: step };
+  const record = {
+    at: new Date().toISOString(),
+    sessionId: state.sessionId,
+    provider,
+    model,
+    mode: 'on',
+    atStep: step,
+  };
   if (!judged.probs) {
     recordEffortDecision({ ...record, skipped: judged.skipped });
     return;
   }
+  const modelMeta = autoEffortModel(provider, state.provider, model);
   const resolved = resolveAutoEffort({
     base: auto.base,
-    options: effortOptionsFor(provider, { id: model }),
+    options: effortOptionsFor(provider, modelMeta),
     probs: judged.probs,
   });
   recordEffortDecision({
@@ -84,6 +96,19 @@ export async function markStepEffort(state, assistantTurnMsg) {
     ms: judged.ms,
     probs: judged.probs.map((value) => Number(value.toFixed(3))),
   });
+  if (snapshot.mode === 'custom') {
+    const level =
+      resolved &&
+      resolveCustomReasoning({
+        protocol: state.provider?.customConfig?.protocol,
+        model: modelMeta,
+        effort: resolved.effort,
+      }).level;
+    if (!level) return;
+    state.opts.effort = level;
+    last.meta = { ...last.meta, effortConfiguration: { ...snapshot, effort: level } };
+    return;
+  }
   const marked = resolved && stepEffortConfiguration(snapshot, provider, model, resolved.effort);
   if (marked) last.meta = { ...last.meta, effortConfiguration: marked };
 }

package/src/runtime/agent/orchestrator/session/manager/ask-turn-auto-effort.mjs

@@ -1,15 +1,17 @@
 // Auto effort for one user turn. The Auto effort built-in (Extensions →
 // Built-in) turns it `on`: the judged effort applies to this turn. The
 // MIXDOG_AUTO_EFFORT env value (off/observe/on) overrides it for diagnostics;
-// `observe` judges and logs without applying. Applies only to user-written
-// prompts on models whose effort can change mid-conversation without
-// invalidating the prompt cache.
+// `observe` judges and logs without applying. Applies to user-written prompts
+// and to agent sessions' briefs and Lead follow-ups (not runtime-injected
+// turns) on models whose effort can change mid-conversation without
+// invalidating the prompt cache, and on custom Chat/Responses routes whose
+// model declares effort levels (the effort is sent with each request).
 import { readSection } from '../../../../shared/config.mjs';
-import { effortConfigurationMode } from '../../providers/effort-configuration.mjs';
+import { autoEffortModel, turnEffortConfigurationMode } from '../../providers/effort-configuration.mjs';
 import { autoEffortBase, normalizeAutoEffortMode, resolveAutoEffort } from '../../providers/auto-effort.mjs';
 import { builtinFeatureActive } from '../../runtime-core/builtin-features.mjs';
 import { effortOptionsFor } from '../../runtime-core/effort.mjs';
-import { judgeTurn, recordEffortDecision } from '../../../../effort-judge/judge-client.mjs';
+import { effortJudgeSupportsSteps, judgeTurn, recordEffortDecision } from '../../../../effort-judge/judge-client.mjs';
 import { promptContentText } from './prompt-utils.mjs';
 
 // Every cache-safe route judges its tool-result steps the same way. Measured
@@ -26,6 +28,17 @@ export function autoEffortStepsEnabled() {
   );
 }
 
+/** `{ request, base }` when each tool-result step of this turn is judged
+ *  (session/loop/step-auto-effort.mjs): auto effort is on for the turn, the
+ *  route has an effort configuration (a mid-conversation update route, or a
+ *  custom Chat/Responses route whose model declares levels), and the installed
+ *  judge was trained on steps. Otherwise null. */
+export function turnStepAutoEffort(autoEffort, effortConfiguration) {
+  return autoEffort?.mode === 'on' && effortConfiguration && autoEffortStepsEnabled() && effortJudgeSupportsSteps()
+    ? { request: autoEffort.request, base: autoEffort.base }
+    : null;
+}
+
 export function autoEffortMode() {
   if (process.env.MIXDOG_AUTO_EFFORT) return normalizeAutoEffortMode(process.env.MIXDOG_AUTO_EFFORT);
   try {
@@ -53,14 +66,14 @@ function lastText(messages, role) {
  */
 export async function resolveTurnAutoEffort({ sessionId, session, provider, input }) {
   const mode = autoEffortMode();
-  // promptSource marks runtime-injected turns (completion notices, queued work);
-  // agent-owned sessions (workers, maintenance) receive runtime-written briefs.
-  if (mode === 'off' || input?.promptSource || session?.owner === 'agent') return null;
+  // promptSource marks runtime-injected turns (completion notices, queued work).
+  // Agent sessions are judged like any other: their spawn brief and later Lead
+  // `send` messages arrive as plain prompts.
+  if (mode === 'off' || input?.promptSource) return null;
   const request = promptContentText(input?.prompt).trim();
   // Skill bodies and runtime blocks arrive as tagged text, not as a request.
   if (!request || request.startsWith('<')) return null;
-  const opts = { ...(provider?.config || {}), modelParameters: session.modelParameters || {} };
-  if (!effortConfigurationMode(session.provider, session.model, opts)) return null;
+  if (!turnEffortConfigurationMode(session, provider)) return null;
   const chosen = String(session.effort || '').toLowerCase();
   const base = autoEffortBase(chosen);
   // The previous user request shows the work a short follow-up continues.
@@ -85,7 +98,7 @@ export async function resolveTurnAutoEffort({ sessionId, session, provider, inpu
   }
   const resolved = resolveAutoEffort({
     base,
-    options: effortOptionsFor(session.provider, { id: session.model }),
+    options: effortOptionsFor(session.provider, autoEffortModel(session.provider, provider, session.model)),
     probs: judged.probs,
   });
   recordEffortDecision({

package/src/runtime/agent/orchestrator/session/manager/ask-turn-execute.mjs

@@ -7,8 +7,7 @@
 import { getProvider } from '../../providers/registry.mjs';
 import { prepareExplicitSkills } from '../explicit-skills.mjs';
 import { prepareTurnEffortConfiguration } from '../../providers/effort-configuration.mjs';
-import { autoEffortStepsEnabled, resolveTurnAutoEffort } from './ask-turn-auto-effort.mjs';
-import { effortJudgeSupportsSteps } from '../../../../effort-judge/judge-client.mjs';
+import { resolveTurnAutoEffort, turnStepAutoEffort } from './ask-turn-auto-effort.mjs';
 import { saveSessionAsync } from '../store.mjs';
 import { hasUserConversationMessage, refreshSessionBp3Environment } from './prompt-utils.mjs';
 import { filterModelVisibleSessionMessages } from './message-sanitize.mjs';
@@ -37,10 +36,7 @@ export async function prepareAskTurn({ sessionId, opened, input, cwdOverride, tr
   );
   // Auto effort also judges every tool-result step of the turn when the
   // installed judge was trained on steps (session/loop/step-auto-effort.mjs).
-  const stepAutoEffort =
-    autoEffort?.mode === 'on' && effortConfiguration && autoEffortStepsEnabled() && effortJudgeSupportsSteps()
-      ? { request: autoEffort.request, base: autoEffort.base }
-      : null;
+  const stepAutoEffort = turnStepAutoEffort(autoEffort, effortConfiguration);
   applyTurnContextMeta(session, provider);
   const effectiveCwd = cwdOverride || session.cwd;
   // A failed-turn retry resubmits the prompt the failure left unanswered;

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

@@ -4,7 +4,9 @@
 // resumeSession (reload tools for a stored session) all share the same tool
 // resolution + context-meta + agent-runtime resolution helpers.
 import { getProvider } from '../../providers/registry.mjs';
+import { invalidateContextUsageSnapshot, invalidateProviderContextBaseline } from '../loop/compact-policy.mjs';
 import { saveSession, saveSessionAsync, saveSessionAsyncDeferred, loadSession, setLiveSession } from '../store.mjs';
+import { _liveSessions } from '../store/live-state.mjs';
 import { _isActivelyOwnedElsewhere, _recoverTurnCheckpointDurably } from './session-owner-liveness.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 import { getHiddenAgent } from '../../internal-agents.mjs';
@@ -44,7 +46,7 @@ export { isSessionOwnerGone, recoverSessionAfterProcessRestart } from './session
 // re-exported so prior importers of this module stay unchanged.
 export { prefetchSession, prepareSessionProjection } from './prepared-resume-cache.mjs';
 
-function buildSessionProviderCacheOpts(providerName, sessionId, agent = null) {
+function buildSessionProviderCacheOpts(providerName, sessionId, agent = null, config = null) {
   // Keep this in sync with createSession's provider-cache policy: only
   // explicit-breakpoint providers get BP cache opts here; OpenAI/key-prefix
   // providers use promptCacheKey and request-time strategy instead, plus the
@@ -55,7 +57,7 @@ function buildSessionProviderCacheOpts(providerName, sessionId, agent = null) {
   try {
     let autoClear = null;
     if (!agent || agent === 'lead') {
-      const loadedConfig = loadConfig({ secrets: false });
+      const loadedConfig = config || loadConfig({ secrets: false });
       const normalizedAutoClear = normalizeAutoClearConfig(loadedConfig?.autoClear);
       autoClear = {
         ...normalizedAutoClear,
@@ -68,6 +70,29 @@ function buildSessionProviderCacheOpts(providerName, sessionId, agent = null) {
   }
 }
 
+// Re-derive a Lead session's builder-made cache policy (messages TTL follows
+// the auto-clear idle window). Explicit caller/profile policies, non-Lead
+// sessions and non-explicit-breakpoint providers are left untouched.
+export function refreshSessionProviderCacheOpts(session, config = null) {
+  if (!session || session.providerCacheOptsOverride === true) return false;
+  if (session.agent && session.agent !== 'lead') return false;
+  if (cacheCapabilityForProvider(session.provider) !== 'explicit-breakpoint') return false;
+  const next = buildSessionProviderCacheOpts(session.provider, session.id, session.agent, config);
+  if (!next) return false;
+  session.providerCacheOpts = next;
+  return true;
+}
+
+// An auto-clear settings change reaches every Lead session held in this
+// process, not only the one on screen; persisted ones refresh on resume.
+export function refreshLiveSessionsProviderCacheOpts(config = null) {
+  let refreshed = 0;
+  for (const session of _liveSessions.values()) {
+    if (refreshSessionProviderCacheOpts(session, config)) refreshed += 1;
+  }
+  return refreshed;
+}
+
 // --- agent spawn (createSession) ---
 // opts can pass either a `preset` object (from config.presets) or raw provider/model.
 // Preset shape: { name, provider, model, effort?, fast?, tools? }
@@ -199,6 +224,7 @@ export function createSession(opts) {
     contextMeta,
     origin: sessionOriginFields(opts, { profile, presetObj, providerCacheOpts, surface }),
   });
+  session.providerCacheOptsOverride = Boolean(resolved.providerCacheOpts);
   refreshSessionBp3Environment(session, opts.cwd);
   // In-process registry + async debounced save: same-process create → load
   // reads live memory; disk flush is for cross-process / restart durability.
@@ -308,6 +334,7 @@ function applyRouteContextWindow(session, routeChanged, selectedContextWindowPro
 function resetSessionForRouteChange(id, session, previousModel, previousProvider) {
   session.promptCacheKey = providerCacheKey(session.provider);
   session.providerCacheOpts = buildSessionProviderCacheOpts(session.provider, session.id, session.agent) || null;
+  session.providerCacheOptsOverride = false;
   session.lastInputTokens = 0;
   session.lastOutputTokens = 0;
   session.lastCachedReadTokens = 0;
@@ -337,7 +364,34 @@ function resetSessionForRouteChange(id, session, previousModel, previousProvider
   _forgetPreparedResume(id);
 }
 
-export function updateSessionRoute(id, route = {}) {
+// Every message field a provider adapter replays or re-reads as native state.
+const PROVIDER_REPLAY_FIELDS = [
+  'providerReplay',
+  'reasoning',
+  'thinkingBlocks',
+  'assistantBlocks',
+  'reasoningItems',
+  'reasoningContent',
+  'providerMetadata',
+];
+
+// Provider-native replay (reasoning items, thinking blocks) belongs to the
+// provider that produced it. Replace, never mutate, so delta saves rewrite.
+function stripProviderReplay(session) {
+  if (!Array.isArray(session.messages)) return;
+  session.messages = session.messages.map((message) => {
+    if (!message || !PROVIDER_REPLAY_FIELDS.some((field) => field in message)) return message;
+    const plain = { ...message };
+    for (const field of PROVIDER_REPLAY_FIELDS) delete plain[field];
+    return plain;
+  });
+}
+
+// `options.crossProvider` is the explicit in-place continuation of an
+// established session on another model: the previous provider's replay state
+// and context readings are dropped so the next turn re-measures (and
+// auto-compacts) against the new model's window.
+export function updateSessionRoute(id, route = {}, options = {}) {
   if (!id) return null;
   const session = loadSession(id);
   if (!session || session.closed === true) return null;
@@ -348,6 +402,11 @@ export function updateSessionRoute(id, route = {}) {
     (route.provider && route.provider !== previousProvider) || (route.model && route.model !== previousModel);
   applyRouteContextWindow(session, routeChanged, Object.hasOwn(route, 'selectedContextWindow'));
   if (routeChanged) resetSessionForRouteChange(id, session, previousModel, previousProvider);
+  if (routeChanged && options.crossProvider === true) {
+    stripProviderReplay(session);
+    invalidateContextUsageSnapshot(session);
+    invalidateProviderContextBaseline(session);
+  }
   // The model feeds the `# Session` prompt block (`Model: …`).
   // Rebuild it here: createSession stamped the block with the creation-time
   // route and set sessionStartMetaInjected, so the ask-time refresh guard
@@ -449,6 +508,7 @@ export async function resumeSession(sessionId, preset, options = {}) {
   if (_isActivelyOwnedElsewhere(session, sessionId)) return _attachViewerSession(session, sessionId);
   _recoverTurnCheckpointDurably(session, sessionId);
   _refreshResumedTools(session, sessionId, preset);
+  refreshSessionProviderCacheOpts(session);
   // The live session already owns the refreshed tools and desktop scope.
   // Defer the structured clone + worker round-trip so opening a conversation
   // is not blocked on persisting the same in-memory state back to disk.

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

@@ -9,15 +9,15 @@ import { collectPromptSkillsCached } from '../../context/collect.mjs';
 import { isAgentOwner } from '../../agent-owner.mjs';
 import { getHiddenAgent } from '../../internal-agents.mjs';
 import { workflowDisallowsAgentTool } from '../../runtime-core/workflow.mjs';
-import { sessionOrchestrationMode } from '../../../../shared/orchestration.mjs';
 import { finalizeSessionToolList, resolveSessionTools, permissionFromToolSpec } from './tool-resolution.mjs';
 import { unusedModelEditToolName } from '../../../../shared/edit-tool-dialect.mjs';
 import { getAgentRuntimeSync } from './agent-runtime-singleton.mjs';
 
-// A lead session may not delegate when orchestration is off or its workflow
-// forbids the agent tool; an agent-owned session never gets the tool anyway.
+// A lead session may not delegate when its workflow forbids the agent tool
+// (no delegatable agents); Solo keeps it deferred for explicit user requests.
+// An agent-owned session never gets the tool anyway.
 export function delegationDisabled(source, ownerIsAgent) {
-  return !ownerIsAgent && (sessionOrchestrationMode(source) === 'none' || workflowDisallowsAgentTool(source?.workflow));
+  return !ownerIsAgent && workflowDisallowsAgentTool(source?.workflow);
 }
 
 // Exactly two schema surfaces exist: Lead and Agent. Every Agent role gets

package/src/runtime/agent/orchestrator/session/transcript-restore/restore.mjs

@@ -52,6 +52,7 @@ function restoredTranscriptMetadata(message) {
     ...(Number.isFinite(Number(value.at)) ? { at: Number(value.at) } : {}),
     ...transcriptRouteMetadataFields(value),
     ...(typeof value.sender === 'string' && value.sender ? { sender: value.sender } : {}),
+    ...(typeof value.device === 'string' && value.device ? { device: value.device } : {}),
     ...(completion ? { completion } : {}),
   };
 }

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

@@ -283,7 +283,6 @@ const WORKFLOW_AGENT_STALL_ABORT_S = {
   reviewer: 300,
   'heavy-worker': 420,
   maintainer: 300,
-  'web-researcher': 300,
 };
 
 export function resolveAgentStallThresholds(agent, env = process.env) {

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

@@ -6,6 +6,7 @@ import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { getAbortSignalForSession } from '../../session/abort-lookup.mjs';
 import { hashText } from './hash-utils.mjs';
+import { fileVersion, sameFileVersion } from './file-version.mjs';
 import { sleep } from '../../../../shared/sleep.mjs';
 import { ioTraceDone, ioTraceStart } from '../io-trace.mjs';
 
@@ -20,13 +21,7 @@ function expectedTargetSnapshotChanged(currentStat, expected) {
   const currentExists = !!currentStat;
   if (snapshotExists !== currentExists) return true;
   if (!snapshotExists || !currentExists) return false;
-  if (currentStat.size !== expected.size) return true;
-  if (Math.abs(Number(currentStat.mtimeMs) - Number(expected.mtimeMs)) > 1) return true;
-  if (Number.isFinite(expected.ctimeMs)) {
-    if (Math.abs(Number(currentStat.ctimeMs) - Number(expected.ctimeMs)) > 1) return true;
-  }
-  if (Number.isFinite(expected.ino) && Number(currentStat.ino) !== Number(expected.ino)) return true;
-  return false;
+  return !sameFileVersion(currentStat, expected);
 }
 
 function atomicWriteShouldFsync(value) {
@@ -180,7 +175,17 @@ async function assertExclusiveCreate(writeTarget, targetPath, tmp) {
 }
 
 async function assertTargetUnchanged(writeTarget, expectedTargetSnapshot, tmp) {
-  if (!expectedTargetSnapshotChanged(statOrNull(writeTarget), expectedTargetSnapshot)) return;
+  let currentStat = null;
+  try {
+    currentStat = statSync(writeTarget);
+  } catch (error) {
+    // A failed lookup is not proof of absence, even for create-only writes.
+    if (error?.code !== 'ENOENT') {
+      await unlinkQuietly(tmp);
+      throw error;
+    }
+  }
+  if (!expectedTargetSnapshotChanged(currentStat, expectedTargetSnapshot)) return;
   await unlinkQuietly(tmp);
   const err = new Error(`target changed between preflight and rename (TOCTOU): ${writeTarget}`);
   err.code = 'ESTALE_TARGET';
@@ -236,6 +241,11 @@ export async function atomicWrite(
   content,
   { mode, signal, sessionId, flags, fsync, preserveMetadata = false, expectedTargetSnapshot } = {}
 ) {
+  // Own the caller's expectation before the first await. Missing fields on
+  // an existing target remain incomplete evidence, not an unguarded write.
+  expectedTargetSnapshot = expectedTargetSnapshot
+    ? { exists: expectedTargetSnapshot.exists !== false, ...fileVersion(expectedTargetSnapshot) }
+    : null;
   const traceStart = ioTraceStart();
   const resolvedSignal = await resolveWriteSignal(signal, sessionId);
   if (resolvedSignal?.aborted) throw abortReasonOf(resolvedSignal);

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

@@ -4,6 +4,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { isAbsolute, sep } from 'node:path';
 import { canonicalCachePath, deleteReadRangeIndexForPath } from './read-range-index.mjs';
 import { resolveAgainstCwd } from './path-utils.mjs';
+import { fileVersion, sameFileVersion } from './file-version.mjs';
 
 const RESULT_CACHE = new Map(); // key → { ts, value, paths, scopes, readSnapshotMeta, contentPrefixHash, bytes }
 const RESULT_CACHE_INFLIGHT = new Map(); // key → { promise, controller, subscribers, settled }
@@ -45,8 +46,8 @@ function resultCacheDelete(key) {
 const STAT_CACHE = new Map(); // fullPath → { ts, stat }
 const STAT_CACHE_TTL_MS = 5_000;
 const STAT_CACHE_MAX_ENTRIES = 2_000;
-const RAW_CONTENT_CACHE = new Map(); // fullPath → { ts, mtimeMs, ctimeMs, size, rawBuf }
-const RAW_CONTENT_INFLIGHT = new Map(); // canonical path → { path, promise }
+const RAW_CONTENT_CACHE = new Map(); // fullPath → { ts, version, rawBuf }
+const RAW_CONTENT_INFLIGHT = new Map(); // path + observed version → { path, promise }
 const RAW_CONTENT_CACHE_TTL_MS = 30_000;
 // 64: a parallel read batch fanning out over a component directory easily
 // tops 16 files; at 16 the batch thrashed its own cache before re-reads hit.
@@ -232,18 +233,21 @@ async function runPathInFlight(inFlight, key, path, start) {
   return await promise;
 }
 
-export async function runRawContentInFlight(fullPath, loader = fsPromises.readFile) {
-  const key = canonicalCachePath(fullPath);
-  return await runPathInFlight(RAW_CONTENT_INFLIGHT, key, key, () => loader(fullPath));
+export async function runRawContentInFlight(fullPath, loader = fsPromises.readFile, stat = undefined) {
+  const path = canonicalCachePath(fullPath);
+  const version = fileVersion(stat);
+  // Buffered reads provide their observed version: a later read must not
+  // join older bytes merely because a watcher has not fired yet. Preserve
+  // the unversioned helper contract for callers that supply no stat.
+  if (stat !== undefined && !version) return await loader(fullPath);
+  const key = version ? JSON.stringify([path, version]) : path;
+  return await runPathInFlight(RAW_CONTENT_INFLIGHT, key, path, () => loader(fullPath));
 }
 
 export async function runReadOnlyStatInFlight(fullPath, loader = fsPromises.stat, kind = 'stat') {
   const canonicalPath = canonicalCachePath(fullPath);
-  return await runPathInFlight(
-    READ_ONLY_STAT_INFLIGHT,
-    `${kind}|${canonicalPath}`,
-    canonicalPath,
-    () => loader(fullPath)
+  return await runPathInFlight(READ_ONLY_STAT_INFLIGHT, `${kind}|${canonicalPath}`, canonicalPath, () =>
+    loader(fullPath)
   );
 }
 
@@ -262,11 +266,7 @@ export function rawContentCacheGet(fullPath, stat, now = Date.now()) {
     rawContentCacheDelete(key);
     return null;
   }
-  if (
-    entry.size !== stat.size ||
-    Math.abs(entry.mtimeMs - stat.mtimeMs) > 1 ||
-    Math.abs(entry.ctimeMs - stat.ctimeMs) > 1
-  ) {
+  if (!sameFileVersion(entry.version, stat)) {
     rawContentCacheDelete(key);
     return null;
   }
@@ -276,15 +276,14 @@ export function rawContentCacheGet(fullPath, stat, now = Date.now()) {
 }
 
 export function rawContentCacheSet(fullPath, stat, rawBuf, now = Date.now()) {
-  if (!fullPath || !stat || !Buffer.isBuffer(rawBuf)) return;
-  if (rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES) return;
+  if (!fullPath || !Buffer.isBuffer(rawBuf)) return;
+  const version = fileVersion(stat);
+  if (!version || rawBuf.length !== version.size || rawBuf.length > RAW_CONTENT_CACHE_MAX_BYTES) return;
   const key = canonicalCachePath(fullPath);
   rawContentCacheDelete(key);
   RAW_CONTENT_CACHE.set(key, {
     ts: now,
-    mtimeMs: stat.mtimeMs,
-    ctimeMs: stat.ctimeMs,
-    size: stat.size,
+    version,
     rawBuf,
   });
   RAW_CONTENT_CACHE_BYTES += rawBuf.length;

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

@@ -14,6 +14,7 @@
 import { readFileSync, mkdirSync, existsSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { atomicWrite, symlinkWriteTarget } from './atomic-write.mjs';
+import { fileVersion } from './file-version.mjs';
 import { assertPathsReachable } from './fs-reachability.mjs';
 import { normalizeInputPath, resolveAgainstCwd, normalizeOutputPath, toDisplayPath } from './path-utils.mjs';
 import {
@@ -476,15 +477,7 @@ function readEditTextForDisplay(fullPath, enc) {
 const SAME_STRINGS_ERROR = 'Error: old_string and new_string are exactly the same';
 
 function targetSnapshot(statBefore) {
-  return statBefore
-    ? {
-        exists: true,
-        size: statBefore.size,
-        mtimeMs: statBefore.mtimeMs,
-        ctimeMs: statBefore.ctimeMs,
-        ino: statBefore.ino,
-      }
-    : { exists: false };
+  return statBefore ? { exists: true, ...fileVersion(statBefore) } : { exists: false };
 }
 
 /**
@@ -493,12 +486,14 @@ function targetSnapshot(statBefore) {
  * Returns `{ error }` when the bytes cannot be read or are not decidable text.
  */
 function readEditTarget(fullPath) {
-  let statBefore = null;
+  // An unreadable pre-stat is incomplete existing-file evidence, not the
+  // explicit absence used by createEditTarget. Never resurrect a removed file.
+  let statBefore = {};
   let content;
   let fileEnc;
   try {
     try {
-      statBefore = statSync(fullPath);
+      statBefore = { ...fileVersion(statSync(fullPath)) };
     } catch {
       /* readFileSync below surfaces the real error */
     }

package/src/runtime/agent/orchestrator/tools/builtin/file-version-test-helpers.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert/strict';
+
+// NTFS identities may exceed Number.MAX_SAFE_INTEGER, where +/- 1 can round
+// back to the original number. Perturb identity, not its precision.
+export function differentFieldValue(current, field, direction = 1) {
+  let value;
+  if (field === 'ino' || field === 'dev') value = current === 0 ? 1 : 0;
+  else value = current + direction * (field.endsWith('Ms') ? 0.5 : 1);
+  assert.notEqual(value, current, `${field} fixture must actually differ`);
+  return value;
+}

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

@@ -0,0 +1,13 @@
+// The exact metadata version of a buffered file body. Missing/non-finite
+// evidence is not equality; never round away a detected sub-ms change.
+const FILE_VERSION_FIELDS = ['mtimeMs', 'ctimeMs', 'size', 'ino', 'dev'];
+
+export function sameFileVersion(a, b) {
+  return !!a && !!b && FILE_VERSION_FIELDS.every((key) => Number.isFinite(a[key]) && a[key] === b[key]);
+}
+
+// Own the fields rather than retaining a mutable Stats/fixture object.
+export function fileVersion(stat) {
+  if (!sameFileVersion(stat, stat)) return null;
+  return Object.fromEntries(FILE_VERSION_FIELDS.map((key) => [key, stat[key]]));
+}