@mastra/memory 1.1.0 → 1.2.0-alpha.0

package/dist/{chunk-FQJWVCDF.cjs → chunk-AWE2QQPI.cjs}

@@ -1,5 +1,7 @@
 'use strict';
 
+var fs = require('fs');
+var path = require('path');
 var agent = require('@mastra/core/agent');
 var llm = require('@mastra/core/llm');
 var memory = require('@mastra/core/memory');
@@ -648,7 +650,7 @@ function parseMultiThreadObserverOutput(output) {
     rawOutput: output
   };
 }
-function buildObserverPrompt(existingObservations, messagesToObserve) {
+function buildObserverPrompt(existingObservations, messagesToObserve, options) {
   const formattedMessages = formatMessagesForObserver(messagesToObserve);
   let prompt = "";
   if (existingObservations) {
@@ -672,6 +674,11 @@ ${formattedMessages}
 
 `;
   prompt += `Extract new observations from the message history above. Do not repeat observations that are already in the previous observations. Add your new observations in the format specified in your instructions.`;
+  if (options?.skipContinuationHints) {
+    prompt += `
+
+IMPORTANT: Do NOT include <current-task> or <suggested-response> sections in your output. Only output <observations>.`;
+  }
   return prompt;
 }
 function parseObserverOutput(output) {
@@ -847,7 +854,9 @@ Hint for the agent's immediate next message. Examples:
 
 User messages are extremely important. If the user asks a question or gives a new task, make it clear in <current-task> that this is the priority. If the assistant needs to respond to the user, indicate in <suggested-response> that it should pause for user reply before continuing other tasks.`;
 }
-var COMPRESSION_RETRY_PROMPT = `
+var COMPRESSION_GUIDANCE = {
+  0: "",
+  1: `
 ## COMPRESSION REQUIRED
 
 Your previous reflection was the same size or larger than the original observations.
@@ -860,8 +869,25 @@ Please re-process with slightly more compression:
 - For example if there is a long nested observation list about repeated tool calls, you can combine those into a single line and observe that the tool was called multiple times for x reason, and finally y outcome happened.
 
 Your current detail level was a 10/10, lets aim for a 8/10 detail level.
-`;
-function buildReflectorPrompt(observations, manualPrompt, compressionRetry) {
+`,
+  2: `
+## AGGRESSIVE COMPRESSION REQUIRED
+
+Your previous reflection was still too large after compression guidance.
+
+Please re-process with much more aggressive compression:
+- Towards the beginning, heavily condense observations into high-level summaries
+- Closer to the end, retain fine details (recent context matters more)
+- Memory is getting very long - use a significantly more condensed style throughout
+- Combine related items aggressively but do not lose important specific details of names, places, events, and people
+- For example if there is a long nested observation list about repeated tool calls, you can combine those into a single line and observe that the tool was called multiple times for x reason, and finally y outcome happened.
+- Remove redundant information and merge overlapping observations
+
+Your current detail level was a 10/10, lets aim for a 6/10 detail level.
+`
+};
+function buildReflectorPrompt(observations, manualPrompt, compressionLevel, skipContinuationHints) {
+  const level = typeof compressionLevel === "number" ? compressionLevel : compressionLevel ? 1 : 0;
   let prompt = `## OBSERVATIONS TO REFLECT ON
 
 ${observations}
@@ -876,10 +902,16 @@ Please analyze these observations and produce a refined, condensed version that
 
 ${manualPrompt}`;
   }
-  if (compressionRetry) {
+  const guidance = COMPRESSION_GUIDANCE[level];
+  if (guidance) {
+    prompt += `
+
+${guidance}`;
+  }
+  if (skipContinuationHints) {
     prompt += `
 
-${COMPRESSION_RETRY_PROMPT}`;
+IMPORTANT: Do NOT include <current-task> or <suggested-response> sections in your output. Only output <observations>.`;
   }
   return prompt;
 }
@@ -1023,6 +1055,43 @@ var TokenCounter = class _TokenCounter {
 };
 
 // src/processors/observational-memory/observational-memory.ts
+var OM_DEBUG_LOG = process.env.OM_DEBUG ? path.join(process.cwd(), "om-debug.log") : null;
+function omDebug(msg) {
+  if (!OM_DEBUG_LOG) return;
+  try {
+    fs.appendFileSync(OM_DEBUG_LOG, `[${(/* @__PURE__ */ new Date()).toLocaleString()}] ${msg}
+`);
+  } catch {
+  }
+}
+function omError(msg, err) {
+  const errStr = err instanceof Error ? err.stack ?? err.message : err !== void 0 ? String(err) : "";
+  const full = errStr ? `${msg}: ${errStr}` : msg;
+  omDebug(`[OM:ERROR] ${full}`);
+}
+omDebug(`[OM:process-start] OM module loaded, pid=${process.pid}`);
+var activeOps = /* @__PURE__ */ new Set();
+function opKey(recordId, op) {
+  return `${recordId}:${op}`;
+}
+function registerOp(recordId, op) {
+  activeOps.add(opKey(recordId, op));
+}
+function unregisterOp(recordId, op) {
+  activeOps.delete(opKey(recordId, op));
+}
+function isOpActiveInProcess(recordId, op) {
+  return activeOps.has(opKey(recordId, op));
+}
+if (OM_DEBUG_LOG) {
+  const _origConsoleError = console.error;
+  console.error = (...args) => {
+    omDebug(
+      `[console.error] ${args.map((a) => a instanceof Error ? a.stack ?? a.message : typeof a === "object" && a !== null ? JSON.stringify(a) : String(a)).join(" ")}`
+    );
+    _origConsoleError.apply(console, args);
+  };
+}
 function formatRelativeTime(date, currentDate) {
   const diffMs = currentDate.getTime() - date.getTime();
   const diffDays = Math.floor(diffMs / (1e3 * 60 * 60 * 24));
@@ -1191,7 +1260,12 @@ var OBSERVATIONAL_MEMORY_DEFAULTS = {
         }
       }
     },
-    maxTokensPerBatch: 1e4
+    maxTokensPerBatch: 1e4,
+    // Async buffering defaults (enabled by default)
+    bufferTokens: 0.2,
+    // Buffer every 20% of messageTokens
+    bufferActivation: 0.8
+    // Activate to retain 20% of threshold
   },
   reflection: {
     model: "google/gemini-2.5-flash",
@@ -1207,10 +1281,13 @@ var OBSERVATIONAL_MEMORY_DEFAULTS = {
           thinkingBudget: 1024
         }
       }
-    }
+    },
+    // Async reflection buffering (enabled by default)
+    bufferActivation: 0.5
+    // Start buffering at 50% of observationTokens
   }
 };
-var ObservationalMemory = class {
+var ObservationalMemory = class _ObservationalMemory {
   id = "observational-memory";
   name = "Observational Memory";
   storage;
@@ -1247,6 +1324,210 @@ var ObservationalMemory = class {
    * accept eventual consistency (acceptable for v1).
    */
   locks = /* @__PURE__ */ new Map();
+  /**
+   * Track in-flight async buffering operations per resource/thread.
+   * STATIC: Shared across all ObservationalMemory instances in this process.
+   * This is critical because multiple OM instances are created per agent loop step,
+   * and we need them to share knowledge of in-flight operations.
+   * Key format: "obs:{lockKey}" or "refl:{lockKey}"
+   * Value: Promise that resolves when buffering completes
+   */
+  static asyncBufferingOps = /* @__PURE__ */ new Map();
+  /**
+   * Track the last token boundary at which we started buffering.
+   * STATIC: Shared across all instances so boundary tracking persists across OM recreations.
+   * Key format: "obs:{lockKey}" or "refl:{lockKey}"
+   */
+  static lastBufferedBoundary = /* @__PURE__ */ new Map();
+  /**
+   * Track the timestamp cursor for buffered messages.
+   * STATIC: Shared across all instances so each buffer only observes messages
+   * newer than the previous buffer's boundary.
+   * Key format: "obs:{lockKey}"
+   */
+  static lastBufferedAtTime = /* @__PURE__ */ new Map();
+  /**
+   * Tracks cycleId for in-flight buffered reflections.
+   * STATIC: Shared across instances so we can match cycleId at activation time.
+   * Key format: "refl:{lockKey}"
+   */
+  static reflectionBufferCycleIds = /* @__PURE__ */ new Map();
+  /**
+   * Track message IDs that have been sealed during async buffering.
+   * STATIC: Shared across all instances so saveMessagesWithSealedIdTracking
+   * generates new IDs when re-saving messages that were sealed in a previous step.
+   * Key format: threadId
+   * Value: Set of sealed message IDs
+   */
+  static sealedMessageIds = /* @__PURE__ */ new Map();
+  /**
+   * Check if async buffering is enabled for observations.
+   */
+  isAsyncObservationEnabled() {
+    const enabled = this.observationConfig.bufferTokens !== void 0 && this.observationConfig.bufferTokens > 0;
+    return enabled;
+  }
+  /**
+   * Check if async buffering is enabled for reflections.
+   * Reflection buffering is enabled when bufferActivation is set (triggers at threshold * bufferActivation).
+   */
+  isAsyncReflectionEnabled() {
+    return this.reflectionConfig.bufferActivation !== void 0 && this.reflectionConfig.bufferActivation > 0;
+  }
+  /**
+   * Get the buffer interval boundary key for observations.
+   */
+  getObservationBufferKey(lockKey) {
+    return `obs:${lockKey}`;
+  }
+  /**
+   * Get the buffer interval boundary key for reflections.
+   */
+  getReflectionBufferKey(lockKey) {
+    return `refl:${lockKey}`;
+  }
+  /**
+   * Clean up static maps for a thread/resource to prevent memory leaks.
+   * Called after activation (to remove activated message IDs from sealedMessageIds)
+   * and from clear() (to fully remove all static state for a thread).
+   */
+  cleanupStaticMaps(threadId, resourceId, activatedMessageIds) {
+    const lockKey = this.getLockKey(threadId, resourceId);
+    const obsBufKey = this.getObservationBufferKey(lockKey);
+    const reflBufKey = this.getReflectionBufferKey(lockKey);
+    if (activatedMessageIds) {
+      const sealedSet = _ObservationalMemory.sealedMessageIds.get(threadId);
+      if (sealedSet) {
+        for (const id of activatedMessageIds) {
+          sealedSet.delete(id);
+        }
+        if (sealedSet.size === 0) {
+          _ObservationalMemory.sealedMessageIds.delete(threadId);
+        }
+      }
+    } else {
+      _ObservationalMemory.sealedMessageIds.delete(threadId);
+      _ObservationalMemory.lastBufferedAtTime.delete(obsBufKey);
+      _ObservationalMemory.lastBufferedBoundary.delete(obsBufKey);
+      _ObservationalMemory.lastBufferedBoundary.delete(reflBufKey);
+      _ObservationalMemory.asyncBufferingOps.delete(obsBufKey);
+      _ObservationalMemory.asyncBufferingOps.delete(reflBufKey);
+      _ObservationalMemory.reflectionBufferCycleIds.delete(obsBufKey);
+    }
+  }
+  /**
+   * Safely get bufferedObservationChunks as an array.
+   * Handles cases where it might be a JSON string or undefined.
+   */
+  getBufferedChunks(record) {
+    if (!record?.bufferedObservationChunks) return [];
+    if (Array.isArray(record.bufferedObservationChunks)) return record.bufferedObservationChunks;
+    if (typeof record.bufferedObservationChunks === "string") {
+      try {
+        const parsed = JSON.parse(record.bufferedObservationChunks);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  }
+  /**
+   * Calculate the projected message tokens that would be removed if activation happened now.
+   * This replicates the chunk boundary logic in swapBufferedToActive without actually activating.
+   */
+  calculateProjectedMessageRemoval(chunks, activationRatio, messageTokensThreshold, currentPendingTokens) {
+    if (chunks.length === 0) return 0;
+    const retentionFloor = messageTokensThreshold * (1 - activationRatio);
+    const targetMessageTokens = Math.max(0, currentPendingTokens - retentionFloor);
+    let cumulativeMessageTokens = 0;
+    let bestBoundary = 0;
+    let bestBoundaryMessageTokens = 0;
+    for (let i = 0; i < chunks.length; i++) {
+      cumulativeMessageTokens += chunks[i].messageTokens ?? 0;
+      const boundary = i + 1;
+      const isUnder = cumulativeMessageTokens <= targetMessageTokens;
+      const bestIsUnder = bestBoundaryMessageTokens <= targetMessageTokens;
+      if (bestBoundary === 0) {
+        bestBoundary = boundary;
+        bestBoundaryMessageTokens = cumulativeMessageTokens;
+      } else if (isUnder && !bestIsUnder) {
+        bestBoundary = boundary;
+        bestBoundaryMessageTokens = cumulativeMessageTokens;
+      } else if (isUnder && bestIsUnder) {
+        if (cumulativeMessageTokens > bestBoundaryMessageTokens) {
+          bestBoundary = boundary;
+          bestBoundaryMessageTokens = cumulativeMessageTokens;
+        }
+      } else if (!isUnder && !bestIsUnder) {
+        if (cumulativeMessageTokens < bestBoundaryMessageTokens) {
+          bestBoundary = boundary;
+          bestBoundaryMessageTokens = cumulativeMessageTokens;
+        }
+      }
+    }
+    if (bestBoundary === 0) {
+      return chunks[0]?.messageTokens ?? 0;
+    }
+    return bestBoundaryMessageTokens;
+  }
+  /**
+   * Check if we've crossed a new bufferTokens interval boundary.
+   * Returns true if async buffering should be triggered.
+   */
+  shouldTriggerAsyncObservation(currentTokens, lockKey, record) {
+    if (!this.isAsyncObservationEnabled()) return false;
+    if (record.isBufferingObservation) {
+      if (isOpActiveInProcess(record.id, "bufferingObservation")) return false;
+      omDebug(`[OM:shouldTriggerAsyncObs] isBufferingObservation=true but stale, clearing`);
+      this.storage.setBufferingObservationFlag(record.id, false).catch(() => {
+      });
+    }
+    const bufferKey = this.getObservationBufferKey(lockKey);
+    if (this.isAsyncBufferingInProgress(bufferKey)) return false;
+    const bufferTokens = this.observationConfig.bufferTokens;
+    const dbBoundary = record.lastBufferedAtTokens ?? 0;
+    const memBoundary = _ObservationalMemory.lastBufferedBoundary.get(bufferKey) ?? 0;
+    const lastBoundary = Math.max(dbBoundary, memBoundary);
+    const currentInterval = Math.floor(currentTokens / bufferTokens);
+    const lastInterval = Math.floor(lastBoundary / bufferTokens);
+    const shouldTrigger = currentInterval > lastInterval;
+    omDebug(
+      `[OM:shouldTriggerAsyncObs] tokens=${currentTokens}, bufferTokens=${bufferTokens}, currentInterval=${currentInterval}, lastInterval=${lastInterval}, lastBoundary=${lastBoundary} (db=${dbBoundary}, mem=${memBoundary}), shouldTrigger=${shouldTrigger}`
+    );
+    return shouldTrigger;
+  }
+  /**
+   * Check if async reflection buffering should be triggered.
+   * Triggers once when observation tokens reach `threshold * bufferActivation`.
+   * Only allows one buffered reflection at a time.
+   */
+  shouldTriggerAsyncReflection(currentObservationTokens, lockKey, record) {
+    if (!this.isAsyncReflectionEnabled()) return false;
+    if (record.isBufferingReflection) {
+      if (isOpActiveInProcess(record.id, "bufferingReflection")) return false;
+      omDebug(`[OM:shouldTriggerAsyncRefl] isBufferingReflection=true but stale, clearing`);
+      this.storage.setBufferingReflectionFlag(record.id, false).catch(() => {
+      });
+    }
+    const bufferKey = this.getReflectionBufferKey(lockKey);
+    if (this.isAsyncBufferingInProgress(bufferKey)) return false;
+    if (_ObservationalMemory.lastBufferedBoundary.has(bufferKey)) return false;
+    if (record.bufferedReflection) return false;
+    const reflectThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+    const activationPoint = reflectThreshold * this.reflectionConfig.bufferActivation;
+    const shouldTrigger = currentObservationTokens >= activationPoint;
+    omDebug(
+      `[OM:shouldTriggerAsyncRefl] obsTokens=${currentObservationTokens}, reflThreshold=${reflectThreshold}, activationPoint=${activationPoint}, bufferActivation=${this.reflectionConfig.bufferActivation}, shouldTrigger=${shouldTrigger}, isBufferingRefl=${record.isBufferingReflection}, hasBufferedReflection=${!!record.bufferedReflection}`
+    );
+    return shouldTrigger;
+  }
+  /**
+   * Check if an async buffering operation is already in progress.
+   */
+  isAsyncBufferingInProgress(bufferKey) {
+    return _ObservationalMemory.asyncBufferingOps.has(bufferKey);
+  }
   /**
    * Acquire a lock for the given key, execute the callback, then release.
    * If a lock is already held, waits for it to be released before acquiring.
@@ -1293,12 +1574,46 @@ var ObservationalMemory = class {
     this.shouldObscureThreadIds = config.obscureThreadIds || false;
     this.storage = config.storage;
     this.scope = config.scope ?? "thread";
-    const observationModel = config.model ?? config.observation?.model ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.model;
-    const reflectionModel = config.model ?? config.reflection?.model ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.model;
+    const resolveModel = (m) => m === "default" ? OBSERVATIONAL_MEMORY_DEFAULTS.observation.model : m;
+    const observationModel = resolveModel(config.model) ?? resolveModel(config.observation?.model) ?? resolveModel(config.reflection?.model);
+    const reflectionModel = resolveModel(config.model) ?? resolveModel(config.reflection?.model) ?? resolveModel(config.observation?.model);
+    if (!observationModel || !reflectionModel) {
+      throw new Error(
+        `Observational Memory requires a model to be set. Use \`observationalMemory: true\` for the default (google/gemini-2.5-flash), or set a model explicitly:
+
+  observationalMemory: {
+    model: "$provider/$model",
+  }
+
+See https://mastra.ai/docs/memory/observational-memory#models for model recommendations and alternatives.`
+      );
+    }
     const messageTokens = config.observation?.messageTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.messageTokens;
     const observationTokens = config.reflection?.observationTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.observationTokens;
     const isSharedBudget = config.shareTokenBudget ?? false;
     const totalBudget = messageTokens + observationTokens;
+    const userExplicitlyConfiguredAsync = config.observation?.bufferTokens !== void 0 || config.observation?.bufferActivation !== void 0 || config.reflection?.bufferActivation !== void 0;
+    const asyncBufferingDisabled = config.observation?.bufferTokens === false || config.scope === "resource" && !userExplicitlyConfiguredAsync;
+    if (isSharedBudget && !asyncBufferingDisabled) {
+      const common = `shareTokenBudget requires async buffering to be disabled (this is a temporary limitation). Add observation: { bufferTokens: false } to your config:
+
+  observationalMemory: {
+    shareTokenBudget: true,
+    observation: { bufferTokens: false },
+  }
+`;
+      if (userExplicitlyConfiguredAsync) {
+        throw new Error(
+          common + `
+Remove any other async buffering settings (bufferTokens, bufferActivation, blockAfter).`
+        );
+      } else {
+        throw new Error(
+          common + `
+Async buffering is enabled by default \u2014 this opt-out is only needed when using shareTokenBudget.`
+        );
+      }
+    }
     this.observationConfig = {
       model: observationModel,
       // When shared budget, store as range: min = base threshold, max = total budget
@@ -1310,7 +1625,16 @@ var ObservationalMemory = class {
         maxOutputTokens: config.observation?.modelSettings?.maxOutputTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.modelSettings.maxOutputTokens
       },
       providerOptions: config.observation?.providerOptions ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.providerOptions,
-      maxTokensPerBatch: config.observation?.maxTokensPerBatch ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.maxTokensPerBatch
+      maxTokensPerBatch: config.observation?.maxTokensPerBatch ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.maxTokensPerBatch,
+      bufferTokens: asyncBufferingDisabled ? void 0 : this.resolveBufferTokens(
+        config.observation?.bufferTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.bufferTokens,
+        config.observation?.messageTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.messageTokens
+      ),
+      bufferActivation: asyncBufferingDisabled ? void 0 : config.observation?.bufferActivation ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.bufferActivation,
+      blockAfter: asyncBufferingDisabled ? void 0 : this.resolveBlockAfter(
+        config.observation?.blockAfter ?? (config.observation?.bufferTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.bufferTokens ? 1.2 : void 0),
+        config.observation?.messageTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.messageTokens
+      )
     };
     this.reflectionConfig = {
       model: reflectionModel,
@@ -1320,11 +1644,20 @@ var ObservationalMemory = class {
         temperature: config.reflection?.modelSettings?.temperature ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.modelSettings.temperature,
         maxOutputTokens: config.reflection?.modelSettings?.maxOutputTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.modelSettings.maxOutputTokens
       },
-      providerOptions: config.reflection?.providerOptions ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.providerOptions
+      providerOptions: config.reflection?.providerOptions ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.providerOptions,
+      bufferActivation: asyncBufferingDisabled ? void 0 : config?.reflection?.bufferActivation ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.bufferActivation,
+      blockAfter: asyncBufferingDisabled ? void 0 : this.resolveBlockAfter(
+        config.reflection?.blockAfter ?? (config.reflection?.bufferActivation ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.bufferActivation ? 1.2 : void 0),
+        config.reflection?.observationTokens ?? OBSERVATIONAL_MEMORY_DEFAULTS.reflection.observationTokens
+      )
     };
     this.tokenCounter = new TokenCounter();
     this.onDebugEvent = config.onDebugEvent;
     this.messageHistory = new processors.MessageHistory({ storage: this.storage });
+    this.validateBufferConfig();
+    omDebug(
+      `[OM:init] new ObservationalMemory instance created \u2014 scope=${this.scope}, messageTokens=${JSON.stringify(this.observationConfig.messageTokens)}, obsAsyncEnabled=${this.isAsyncObservationEnabled()}, bufferTokens=${this.observationConfig.bufferTokens}, bufferActivation=${this.observationConfig.bufferActivation}, blockAfter=${this.observationConfig.blockAfter}, reflectionTokens=${this.reflectionConfig.observationTokens}, refAsyncEnabled=${this.isAsyncReflectionEnabled()}, refAsyncActivation=${this.reflectionConfig.bufferActivation}, refBlockAfter=${this.reflectionConfig.blockAfter}`
+    );
   }
   /**
    * Get the current configuration for this OM instance.
@@ -1348,7 +1681,7 @@ var ObservationalMemory = class {
   async getResolvedConfig(requestContext) {
     const getModelToResolve = (model) => {
       if (Array.isArray(model)) {
-        return model[0]?.model ?? OBSERVATIONAL_MEMORY_DEFAULTS.observation.model;
+        return model[0]?.model ?? "unknown";
       }
       return model;
     };
@@ -1361,7 +1694,7 @@ var ObservationalMemory = class {
         const resolved = await llm.resolveModelConfig(modelToResolve, requestContext);
         return formatModelName(resolved);
       } catch (error) {
-        console.error("[OM] Failed to resolve model config:", error);
+        omError("[OM] Failed to resolve model config", error);
         return "(unknown)";
       }
     };
@@ -1389,24 +1722,96 @@ var ObservationalMemory = class {
       this.onDebugEvent(event);
     }
   }
-  // ASYNC BUFFERING DISABLED - See note at top of file
-  // /**
-  //  * Validate that bufferEvery is less than the threshold
-  //  */
-  // private validateBufferConfig(): void {
-  //   const observationThreshold = this.getMaxThreshold(this.observationConfig.messageTokens);
-  //   if (this.observationConfig.bufferEvery && this.observationConfig.bufferEvery >= observationThreshold) {
-  //     throw new Error(
-  //       `observation.bufferEvery (${this.observationConfig.bufferEvery}) must be less than messageTokens (${observationThreshold})`,
-  //     );
-  //   }
-  //   const reflectionThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
-  //   if (this.reflectionConfig.bufferEvery && this.reflectionConfig.bufferEvery >= reflectionThreshold) {
-  //     throw new Error(
-  //       `reflection.bufferEvery (${this.reflectionConfig.bufferEvery}) must be less than observationTokens (${reflectionThreshold})`,
-  //     );
-  //   }
-  // }
+  /**
+   * Validate buffer configuration on first use.
+   * Ensures bufferTokens is less than the threshold and bufferActivation is valid.
+   */
+  validateBufferConfig() {
+    const hasAsyncBuffering = this.observationConfig.bufferTokens !== void 0 || this.observationConfig.bufferActivation !== void 0 || this.reflectionConfig.bufferActivation !== void 0;
+    if (hasAsyncBuffering && this.scope === "resource") {
+      throw new Error(
+        `Async buffering is not yet supported with scope: 'resource'. Use scope: 'thread', or set observation: { bufferTokens: false } to disable async buffering.`
+      );
+    }
+    const observationThreshold = this.getMaxThreshold(this.observationConfig.messageTokens);
+    if (this.observationConfig.bufferTokens !== void 0) {
+      if (this.observationConfig.bufferTokens <= 0) {
+        throw new Error(`observation.bufferTokens must be > 0, got ${this.observationConfig.bufferTokens}`);
+      }
+      if (this.observationConfig.bufferTokens >= observationThreshold) {
+        throw new Error(
+          `observation.bufferTokens (${this.observationConfig.bufferTokens}) must be less than messageTokens (${observationThreshold})`
+        );
+      }
+    }
+    if (this.observationConfig.bufferActivation !== void 0) {
+      if (this.observationConfig.bufferActivation <= 0 || this.observationConfig.bufferActivation > 1) {
+        throw new Error(
+          `observation.bufferActivation must be in range (0, 1], got ${this.observationConfig.bufferActivation}`
+        );
+      }
+    }
+    if (this.observationConfig.blockAfter !== void 0) {
+      if (this.observationConfig.blockAfter < observationThreshold) {
+        throw new Error(
+          `observation.blockAfter (${this.observationConfig.blockAfter}) must be >= messageTokens (${observationThreshold})`
+        );
+      }
+      if (!this.observationConfig.bufferTokens) {
+        throw new Error(
+          `observation.blockAfter requires observation.bufferTokens to be set (blockAfter only applies when async buffering is enabled)`
+        );
+      }
+    }
+    if (this.reflectionConfig.bufferActivation !== void 0) {
+      if (this.reflectionConfig.bufferActivation <= 0 || this.reflectionConfig.bufferActivation > 1) {
+        throw new Error(
+          `reflection.bufferActivation must be in range (0, 1], got ${this.reflectionConfig.bufferActivation}`
+        );
+      }
+    }
+    if (this.reflectionConfig.blockAfter !== void 0) {
+      const reflectionThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+      if (this.reflectionConfig.blockAfter < reflectionThreshold) {
+        throw new Error(
+          `reflection.blockAfter (${this.reflectionConfig.blockAfter}) must be >= reflection.observationTokens (${reflectionThreshold})`
+        );
+      }
+      if (!this.reflectionConfig.bufferActivation) {
+        throw new Error(
+          `reflection.blockAfter requires reflection.bufferActivation to be set (blockAfter only applies when async reflection is enabled)`
+        );
+      }
+    }
+  }
+  /**
+   * Resolve bufferTokens: if it's a fraction (0 < value < 1), multiply by messageTokens threshold.
+   * Otherwise return the absolute token count.
+   */
+  resolveBufferTokens(bufferTokens, messageTokens) {
+    if (bufferTokens === false) return void 0;
+    if (bufferTokens === void 0) return void 0;
+    if (bufferTokens > 0 && bufferTokens < 1) {
+      const threshold = typeof messageTokens === "number" ? messageTokens : messageTokens.max;
+      return Math.round(threshold * bufferTokens);
+    }
+    return bufferTokens;
+  }
+  /**
+   * Resolve blockAfter config value.
+   * Values between 1 and 2 (exclusive) are treated as multipliers of the threshold.
+   * e.g. blockAfter: 1.5 with messageTokens: 20_000 → 30_000
+   * Values >= 2 are treated as absolute token counts.
+   * Defaults to 1.2 (120% of threshold) when async buffering is enabled but blockAfter is omitted.
+   */
+  resolveBlockAfter(blockAfter, messageTokens) {
+    if (blockAfter === void 0) return void 0;
+    if (blockAfter >= 1 && blockAfter < 2) {
+      const threshold = typeof messageTokens === "number" ? messageTokens : messageTokens.max;
+      return Math.round(threshold * blockAfter);
+    }
+    return blockAfter;
+  }
   /**
    * Get the maximum value from a threshold (simple number or range)
    */
@@ -1596,6 +2001,112 @@ var ObservationalMemory = class {
       }
     };
   }
+  /**
+   * Create a start marker for when async buffering begins.
+   */
+  createBufferingStartMarker(params) {
+    return {
+      type: "data-om-buffering-start",
+      data: {
+        cycleId: params.cycleId,
+        operationType: params.operationType,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        tokensToBuffer: params.tokensToBuffer,
+        recordId: params.recordId,
+        threadId: params.threadId,
+        threadIds: params.threadIds,
+        config: this.getObservationMarkerConfig()
+      }
+    };
+  }
+  /**
+   * Create an end marker for when async buffering completes successfully.
+   */
+  createBufferingEndMarker(params) {
+    const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const durationMs = new Date(completedAt).getTime() - new Date(params.startedAt).getTime();
+    return {
+      type: "data-om-buffering-end",
+      data: {
+        cycleId: params.cycleId,
+        operationType: params.operationType,
+        completedAt,
+        durationMs,
+        tokensBuffered: params.tokensBuffered,
+        bufferedTokens: params.bufferedTokens,
+        recordId: params.recordId,
+        threadId: params.threadId,
+        observations: params.observations
+      }
+    };
+  }
+  /**
+   * Create a failed marker for when async buffering fails.
+   */
+  createBufferingFailedMarker(params) {
+    const failedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const durationMs = new Date(failedAt).getTime() - new Date(params.startedAt).getTime();
+    return {
+      type: "data-om-buffering-failed",
+      data: {
+        cycleId: params.cycleId,
+        operationType: params.operationType,
+        failedAt,
+        durationMs,
+        tokensAttempted: params.tokensAttempted,
+        error: params.error,
+        recordId: params.recordId,
+        threadId: params.threadId
+      }
+    };
+  }
+  /**
+   * Create an activation marker for when buffered observations are activated.
+   */
+  createActivationMarker(params) {
+    return {
+      type: "data-om-activation",
+      data: {
+        cycleId: params.cycleId,
+        operationType: params.operationType,
+        activatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        chunksActivated: params.chunksActivated,
+        tokensActivated: params.tokensActivated,
+        observationTokens: params.observationTokens,
+        messagesActivated: params.messagesActivated,
+        recordId: params.recordId,
+        threadId: params.threadId,
+        generationCount: params.generationCount,
+        config: this.getObservationMarkerConfig(),
+        observations: params.observations
+      }
+    };
+  }
+  /**
+   * Persist a data-om-* marker part on the last assistant message in messageList
+   * AND save the updated message to the DB so it survives page reload.
+   * (data-* parts are filtered out before sending to the LLM, so they don't affect model calls.)
+   */
+  async persistMarkerToMessage(marker, messageList, threadId, resourceId) {
+    if (!messageList) return;
+    const allMsgs = messageList.get.all.db();
+    for (let i = allMsgs.length - 1; i >= 0; i--) {
+      const msg = allMsgs[i];
+      if (msg?.role === "assistant" && msg.content?.parts && Array.isArray(msg.content.parts)) {
+        msg.content.parts.push(marker);
+        try {
+          await this.messageHistory.persistMessages({
+            messages: [msg],
+            threadId,
+            resourceId
+          });
+        } catch (e) {
+          omDebug(`[OM:persistMarker] failed to save marker to DB: ${e}`);
+        }
+        return;
+      }
+    }
+  }
   /**
    * Find the last completed observation boundary in a message's parts.
    * A completed observation is a start marker followed by an end marker.
@@ -1633,6 +2144,44 @@ var ObservationalMemory = class {
     }
     return lastStartIndex !== -1 && lastStartIndex > lastEndOrFailedIndex;
   }
+  /**
+   * Seal messages to prevent new parts from being merged into them.
+   * This is used when starting buffering to capture the current content state.
+   *
+   * Sealing works by:
+   * 1. Setting `message.content.metadata.mastra.sealed = true` (message-level flag)
+   * 2. Adding `metadata.mastra.sealedAt` to the last part (boundary marker)
+   *
+   * When MessageList.add() receives a message with the same ID as a sealed message,
+   * it creates a new message with only the parts beyond the seal boundary.
+   *
+   * The messages are mutated in place - since they're references to the same objects
+   * in the MessageList, the seal will be recognized immediately.
+   *
+   * @param messages - Messages to seal (mutated in place)
+   */
+  sealMessagesForBuffering(messages) {
+    const sealedAt = Date.now();
+    for (const msg of messages) {
+      if (!msg.content?.parts?.length) continue;
+      if (!msg.content.metadata) {
+        msg.content.metadata = {};
+      }
+      const metadata = msg.content.metadata;
+      if (!metadata.mastra) {
+        metadata.mastra = {};
+      }
+      metadata.mastra.sealed = true;
+      const lastPart = msg.content.parts[msg.content.parts.length - 1];
+      if (!lastPart.metadata) {
+        lastPart.metadata = {};
+      }
+      if (!lastPart.metadata.mastra) {
+        lastPart.metadata.mastra = {};
+      }
+      lastPart.metadata.mastra.sealedAt = sealedAt;
+    }
+  }
   /**
    * Insert an observation marker into a message.
    * The marker is appended directly to the message's parts array (mutating in place).
@@ -1699,10 +2248,22 @@ var ObservationalMemory = class {
    * This handles the case where a single message accumulates many parts
    * (like tool calls) during an agentic loop - we only observe the new parts.
    */
-  getUnobservedMessages(allMessages, record) {
+  getUnobservedMessages(allMessages, record, opts) {
     const lastObservedAt = record.lastObservedAt;
-    const observedMessageIds = Array.isArray(record.observedMessageIds) ? new Set(record.observedMessageIds) : void 0;
-    if (!lastObservedAt) {
+    const observedMessageIds = new Set(
+      Array.isArray(record.observedMessageIds) ? record.observedMessageIds : []
+    );
+    if (opts?.excludeBuffered) {
+      const bufferedChunks = this.getBufferedChunks(record);
+      for (const chunk of bufferedChunks) {
+        if (Array.isArray(chunk.messageIds)) {
+          for (const id of chunk.messageIds) {
+            observedMessageIds.add(id);
+          }
+        }
+      }
+    }
+    if (!lastObservedAt && observedMessageIds.size === 0) {
       return allMessages;
     }
     const result = [];
@@ -1720,7 +2281,7 @@ var ObservationalMemory = class {
           result.push(virtualMsg);
         }
       } else {
-        if (!msg.createdAt) {
+        if (!msg.createdAt || !lastObservedAt) {
           result.push(msg);
         } else {
           const msgDate = new Date(msg.createdAt);
@@ -1751,16 +2312,16 @@ var ObservationalMemory = class {
   /**
    * Call the Observer agent to extract observations.
    */
-  async callObserver(existingObservations, messagesToObserve, abortSignal) {
+  async callObserver(existingObservations, messagesToObserve, abortSignal, options) {
     const agent = this.getObserverAgent();
-    const prompt = buildObserverPrompt(existingObservations, messagesToObserve);
+    const prompt = buildObserverPrompt(existingObservations, messagesToObserve, options);
     const result = await this.withAbortCheck(
       () => agent.generate(prompt, {
         modelSettings: {
           ...this.observationConfig.modelSettings
         },
         providerOptions: this.observationConfig.providerOptions,
-        abortSignal
+        ...abortSignal ? { abortSignal } : {}
       }),
       abortSignal
     );
@@ -1804,7 +2365,7 @@ var ObservationalMemory = class {
           ...this.observationConfig.modelSettings
         },
         providerOptions: this.observationConfig.providerOptions,
-        abortSignal
+        ...abortSignal ? { abortSignal } : {}
       }),
       abortSignal
     );
@@ -1836,21 +2397,48 @@ var ObservationalMemory = class {
    * Call the Reflector agent to condense observations.
    * Includes compression validation and retry logic.
    */
-  async callReflector(observations, manualPrompt, streamContext, observationTokensThreshold, abortSignal) {
+  async callReflector(observations, manualPrompt, streamContext, observationTokensThreshold, abortSignal, skipContinuationHints, compressionStartLevel) {
     const agent = this.getReflectorAgent();
     const originalTokens = this.tokenCounter.countObservations(observations);
     const targetThreshold = observationTokensThreshold ?? this.getMaxThreshold(this.reflectionConfig.observationTokens);
     let totalUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
-    let prompt = buildReflectorPrompt(observations, manualPrompt, false);
-    let result = await this.withAbortCheck(
-      () => agent.generate(prompt, {
-        modelSettings: {
-          ...this.reflectionConfig.modelSettings
-        },
-        providerOptions: this.reflectionConfig.providerOptions,
-        abortSignal
-      }),
-      abortSignal
+    const firstLevel = compressionStartLevel ?? 0;
+    const retryLevel = Math.min(firstLevel + 1, 2);
+    let prompt = buildReflectorPrompt(observations, manualPrompt, firstLevel, skipContinuationHints);
+    omDebug(
+      `[OM:callReflector] starting first attempt: originalTokens=${originalTokens}, targetThreshold=${targetThreshold}, promptLen=${prompt.length}, skipContinuationHints=${skipContinuationHints}`
+    );
+    let chunkCount = 0;
+    const generatePromise = agent.generate(prompt, {
+      modelSettings: {
+        ...this.reflectionConfig.modelSettings
+      },
+      providerOptions: this.reflectionConfig.providerOptions,
+      ...abortSignal ? { abortSignal } : {},
+      onChunk(chunk) {
+        chunkCount++;
+        if (chunkCount === 1 || chunkCount % 50 === 0) {
+          const preview = chunk.type === "text-delta" ? ` text="${chunk.textDelta?.slice(0, 80)}..."` : chunk.type === "tool-call" ? ` tool=${chunk.toolName}` : "";
+          omDebug(`[OM:callReflector] chunk#${chunkCount}: type=${chunk.type}${preview}`);
+        }
+      },
+      onFinish(event) {
+        omDebug(
+          `[OM:callReflector] onFinish: chunks=${chunkCount}, finishReason=${event.finishReason}, inputTokens=${event.usage?.inputTokens}, outputTokens=${event.usage?.outputTokens}, textLen=${event.text?.length}`
+        );
+      },
+      onAbort(event) {
+        omDebug(`[OM:callReflector] onAbort: chunks=${chunkCount}, reason=${event?.reason ?? "unknown"}`);
+      },
+      onError({ error }) {
+        omError(`[OM:callReflector] onError after ${chunkCount} chunks`, error);
+      }
+    });
+    let result = await this.withAbortCheck(async () => {
+      return await generatePromise;
+    }, abortSignal);
+    omDebug(
+      `[OM:callReflector] first attempt returned: textLen=${result.text?.length}, textPreview="${result.text?.slice(0, 120)}...", inputTokens=${result.usage?.inputTokens ?? result.totalUsage?.inputTokens}, outputTokens=${result.usage?.outputTokens ?? result.totalUsage?.outputTokens}, keys=${Object.keys(result).join(",")}`
     );
     const firstUsage = result.totalUsage ?? result.usage;
     if (firstUsage) {
@@ -1860,6 +2448,9 @@ var ObservationalMemory = class {
     }
     let parsed = parseReflectorOutput(result.text);
     let reflectedTokens = this.tokenCounter.countObservations(parsed.observations);
+    omDebug(
+      `[OM:callReflector] first attempt parsed: reflectedTokens=${reflectedTokens}, targetThreshold=${targetThreshold}, compressionValid=${validateCompression(reflectedTokens, targetThreshold)}, parsedObsLen=${parsed.observations?.length}`
+    );
     if (!validateCompression(reflectedTokens, targetThreshold)) {
       if (streamContext?.writer) {
         const failedMarker = this.createObservationFailedMarker({
@@ -1887,17 +2478,21 @@ var ObservationalMemory = class {
         await streamContext.writer.custom(startMarker).catch(() => {
         });
       }
-      prompt = buildReflectorPrompt(observations, manualPrompt, true);
+      prompt = buildReflectorPrompt(observations, manualPrompt, retryLevel, skipContinuationHints);
+      omDebug(`[OM:callReflector] starting retry: promptLen=${prompt.length}`);
       result = await this.withAbortCheck(
         () => agent.generate(prompt, {
           modelSettings: {
             ...this.reflectionConfig.modelSettings
           },
           providerOptions: this.reflectionConfig.providerOptions,
-          abortSignal
+          ...abortSignal ? { abortSignal } : {}
         }),
         abortSignal
       );
+      omDebug(
+        `[OM:callReflector] retry returned: textLen=${result.text?.length}, inputTokens=${result.usage?.inputTokens ?? result.totalUsage?.inputTokens}, outputTokens=${result.usage?.outputTokens ?? result.totalUsage?.outputTokens}`
+      );
       const retryUsage = result.totalUsage ?? result.usage;
       if (retryUsage) {
         totalUsage.inputTokens += retryUsage.inputTokens ?? 0;
@@ -1906,6 +2501,9 @@ var ObservationalMemory = class {
       }
       parsed = parseReflectorOutput(result.text);
       reflectedTokens = this.tokenCounter.countObservations(parsed.observations);
+      omDebug(
+        `[OM:callReflector] retry parsed: reflectedTokens=${reflectedTokens}, compressionValid=${validateCompression(reflectedTokens, targetThreshold)}`
+      );
     }
     return {
       observations: parsed.observations,
@@ -1988,34 +2586,34 @@ ${suggestedResponse}
     }
     return null;
   }
+  // ══════════════════════════════════════════════════════════════════════════
+  // PROCESS INPUT STEP HELPERS
+  // These helpers extract logical units from processInputStep for clarity.
+  // ══════════════════════════════════════════════════════════════════════════
   /**
-   * Process input at each step - check threshold, observe if needed, save, inject observations.
-   * This is the ONLY processor method - all OM logic happens here.
-   *
-   * Flow:
-   * 1. Load historical messages (step 0 only)
-   * 2. Check if observation threshold is reached
-   * 3. If threshold reached: observe, save messages with markers
-   * 4. Inject observations into context
-   * 5. Filter out already-observed messages
+   * Load historical unobserved messages into the message list (step 0 only).
+   * In resource scope, loads only current thread's messages.
+   * In thread scope, loads all unobserved messages for the thread.
    */
-  async processInputStep(args) {
-    const { messageList, requestContext, stepNumber, state: _state, writer, abortSignal, abort } = args;
-    const state = _state ?? {};
-    const context = this.getThreadContext(requestContext, messageList);
-    if (!context) {
-      return messageList;
+  async loadHistoricalMessagesIfNeeded(messageList, state, threadId, resourceId, lastObservedAt) {
+    if (state.initialSetupDone) {
+      return;
     }
-    const { threadId, resourceId } = context;
-    const memoryContext = memory.parseMemoryRequestContext(requestContext);
-    const readOnly = memoryContext?.memoryConfig?.readOnly;
-    let record = await this.getOrCreateRecord(threadId, resourceId);
-    if (!state.initialSetupDone) {
-      state.initialSetupDone = true;
-      const lastObservedAt = record.lastObservedAt;
-      if (this.scope === "resource" && resourceId) {
-        const currentThreadMessages = await this.loadUnobservedMessages(threadId, void 0, lastObservedAt);
-        for (const msg of currentThreadMessages) {
+    state.initialSetupDone = true;
+    if (this.scope === "resource" && resourceId) {
+      const currentThreadMessages = await this.loadUnobservedMessages(threadId, void 0, lastObservedAt);
+      for (const msg of currentThreadMessages) {
+        if (msg.role !== "system") {
+          if (!this.hasUnobservedParts(msg) && this.findLastCompletedObservationBoundary(msg) !== -1) {
+            continue;
+          }
+          messageList.add(msg, "memory");
+        }
+      }
+    } else {
+      const historicalMessages = await this.loadUnobservedMessages(threadId, resourceId, lastObservedAt);
+      if (historicalMessages.length > 0) {
+        for (const msg of historicalMessages) {
           if (msg.role !== "system") {
             if (!this.hasUnobservedParts(msg) && this.findLastCompletedObservationBoundary(msg) !== -1) {
               continue;
@@ -2023,261 +2621,637 @@ ${suggestedResponse}
             messageList.add(msg, "memory");
           }
         }
-      } else {
-        const historicalMessages = await this.loadUnobservedMessages(threadId, resourceId, lastObservedAt);
-        if (historicalMessages.length > 0) {
-          for (const msg of historicalMessages) {
-            if (msg.role !== "system") {
-              if (!this.hasUnobservedParts(msg) && this.findLastCompletedObservationBoundary(msg) !== -1) {
-                continue;
-              }
-              messageList.add(msg, "memory");
-            }
-          }
-        }
       }
     }
-    let unobservedContextBlocks;
-    if (this.scope === "resource" && resourceId) {
-      unobservedContextBlocks = await this.loadOtherThreadsContext(resourceId, threadId);
-    }
-    if (!readOnly) {
-      const allMessages = messageList.get.all.db();
-      const unobservedMessages = this.getUnobservedMessages(allMessages, record);
-      const currentSessionTokens = this.tokenCounter.countMessages(unobservedMessages);
-      const otherThreadTokens = unobservedContextBlocks ? this.tokenCounter.countString(unobservedContextBlocks) : 0;
-      const currentObservationTokens = record.observationTokenCount ?? 0;
-      const pendingTokens = record.pendingMessageTokens ?? 0;
-      const totalPendingTokens = pendingTokens + currentSessionTokens + otherThreadTokens;
-      const threshold = this.calculateDynamicThreshold(this.observationConfig.messageTokens, currentObservationTokens);
-      const baseReflectionThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
-      const isSharedBudget = typeof this.observationConfig.messageTokens !== "number";
-      const totalBudget = isSharedBudget ? this.observationConfig.messageTokens.max : 0;
-      const effectiveObservationTokensThreshold = isSharedBudget ? Math.max(totalBudget - threshold, 1e3) : baseReflectionThreshold;
-      const observationTokensPercent = Math.round(
-        currentObservationTokens / effectiveObservationTokensThreshold * 100
+  }
+  /**
+   * Calculate all threshold-related values for observation decision making.
+   */
+  calculateObservationThresholds(allMessages, _unobservedMessages, _pendingTokens, otherThreadTokens, currentObservationTokens, _record) {
+    const contextWindowTokens = this.tokenCounter.countMessages(allMessages);
+    const totalPendingTokens = Math.max(0, contextWindowTokens + otherThreadTokens);
+    const threshold = this.calculateDynamicThreshold(this.observationConfig.messageTokens, currentObservationTokens);
+    const baseReflectionThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+    const isSharedBudget = typeof this.observationConfig.messageTokens !== "number";
+    const totalBudget = isSharedBudget ? this.observationConfig.messageTokens.max : 0;
+    const effectiveObservationTokensThreshold = isSharedBudget ? Math.max(totalBudget - threshold, 1e3) : baseReflectionThreshold;
+    return {
+      totalPendingTokens,
+      threshold,
+      effectiveObservationTokensThreshold,
+      isSharedBudget
+    };
+  }
+  /**
+   * Emit debug event and stream progress part for UI feedback.
+   */
+  async emitStepProgress(writer, threadId, resourceId, stepNumber, record, thresholds, currentObservationTokens) {
+    const { totalPendingTokens, threshold, effectiveObservationTokensThreshold } = thresholds;
+    this.emitDebugEvent({
+      type: "step_progress",
+      timestamp: /* @__PURE__ */ new Date(),
+      threadId,
+      resourceId: resourceId ?? "",
+      stepNumber,
+      finishReason: "unknown",
+      pendingTokens: totalPendingTokens,
+      threshold,
+      thresholdPercent: Math.round(totalPendingTokens / threshold * 100),
+      willSave: totalPendingTokens >= threshold,
+      willObserve: totalPendingTokens >= threshold
+    });
+    if (writer) {
+      const bufferedChunks = this.getBufferedChunks(record);
+      const bufferedObservationTokens = bufferedChunks.reduce((sum, chunk) => sum + (chunk.tokenCount ?? 0), 0);
+      const rawBufferedMessageTokens = bufferedChunks.reduce((sum, chunk) => sum + (chunk.messageTokens ?? 0), 0);
+      const bufferedMessageTokens = Math.min(rawBufferedMessageTokens, totalPendingTokens);
+      const projectedMessageRemoval = this.calculateProjectedMessageRemoval(
+        bufferedChunks,
+        this.observationConfig.bufferActivation ?? 1,
+        this.getMaxThreshold(this.observationConfig.messageTokens),
+        totalPendingTokens
       );
-      this.emitDebugEvent({
-        type: "step_progress",
-        timestamp: /* @__PURE__ */ new Date(),
-        threadId,
-        resourceId: resourceId ?? "",
-        stepNumber,
-        finishReason: "unknown",
-        pendingTokens: totalPendingTokens,
-        threshold,
-        thresholdPercent: Math.round(totalPendingTokens / threshold * 100),
-        willSave: totalPendingTokens >= threshold,
-        willObserve: totalPendingTokens >= threshold
-      });
-      if (writer) {
-        const progressPart = {
-          type: "data-om-progress",
-          data: {
-            pendingTokens: totalPendingTokens,
-            messageTokens: threshold,
-            messageTokensPercent: Math.round(totalPendingTokens / threshold * 100),
-            observationTokens: currentObservationTokens,
-            observationTokensThreshold: effectiveObservationTokensThreshold,
-            observationTokensPercent,
-            willObserve: totalPendingTokens >= threshold,
-            recordId: record.id,
-            threadId,
-            stepNumber
-          }
-        };
-        await writer.custom(progressPart).catch(() => {
-        });
+      let obsBufferStatus = "idle";
+      if (record.isBufferingObservation) {
+        obsBufferStatus = "running";
+      } else if (bufferedChunks.length > 0) {
+        obsBufferStatus = "complete";
       }
-      const sealedIds = state.sealedIds ?? /* @__PURE__ */ new Set();
-      if (stepNumber > 0 && totalPendingTokens >= threshold) {
-        const lockKey = this.getLockKey(threadId, resourceId);
-        let observationSucceeded = false;
-        await this.withLock(lockKey, async () => {
-          const freshRecord = await this.getOrCreateRecord(threadId, resourceId);
-          const freshAllMessages = messageList.get.all.db();
-          const freshUnobservedMessages = this.getUnobservedMessages(freshAllMessages, freshRecord);
-          const freshCurrentTokens = this.tokenCounter.countMessages(freshUnobservedMessages);
-          const freshPending = freshRecord.pendingMessageTokens ?? 0;
-          let freshOtherThreadTokens = 0;
-          if (this.scope === "resource" && resourceId) {
-            const freshOtherContext = await this.loadOtherThreadsContext(resourceId, threadId);
-            freshOtherThreadTokens = freshOtherContext ? this.tokenCounter.countString(freshOtherContext) : 0;
-          }
-          const freshTotal = freshPending + freshCurrentTokens + freshOtherThreadTokens;
-          if (freshTotal < threshold) {
-            return;
-          }
-          const preObservationTime = freshRecord.lastObservedAt?.getTime() ?? 0;
-          if (freshUnobservedMessages.length > 0) {
-            try {
-              if (this.scope === "resource" && resourceId) {
-                await this.doResourceScopedObservation(
-                  freshRecord,
-                  threadId,
-                  resourceId,
-                  freshUnobservedMessages,
-                  writer,
-                  abortSignal
-                );
-              } else {
-                await this.doSynchronousObservation(
-                  freshRecord,
-                  threadId,
-                  freshUnobservedMessages,
-                  writer,
-                  abortSignal
-                );
+      let refBufferStatus = "idle";
+      if (record.isBufferingReflection) {
+        refBufferStatus = "running";
+      } else if (record.bufferedReflection && record.bufferedReflection.length > 0) {
+        refBufferStatus = "complete";
+      }
+      const statusPart = {
+        type: "data-om-status",
+        data: {
+          windows: {
+            active: {
+              messages: {
+                tokens: totalPendingTokens,
+                threshold
+              },
+              observations: {
+                tokens: currentObservationTokens,
+                threshold: effectiveObservationTokensThreshold
               }
-              const updatedRecord = await this.getOrCreateRecord(threadId, resourceId);
-              const updatedTime = updatedRecord.lastObservedAt?.getTime() ?? 0;
-              observationSucceeded = updatedTime > preObservationTime;
-            } catch (error) {
-              if (abortSignal?.aborted) {
-                abort("Agent execution was aborted");
-              } else {
-                abort(
-                  `Encountered error during memory observation ${error instanceof Error ? error.message : JSON.stringify(error, null, 2)}`
-                );
+            },
+            buffered: {
+              observations: {
+                chunks: bufferedChunks.length,
+                messageTokens: bufferedMessageTokens,
+                projectedMessageRemoval,
+                observationTokens: bufferedObservationTokens,
+                status: obsBufferStatus
+              },
+              reflection: {
+                inputObservationTokens: record.bufferedReflectionInputTokens ?? 0,
+                observationTokens: record.bufferedReflectionTokens ?? 0,
+                status: refBufferStatus
               }
-              observationSucceeded = false;
             }
+          },
+          recordId: record.id,
+          threadId,
+          stepNumber,
+          generationCount: record.generationCount
+        }
+      };
+      omDebug(
+        `[OM:status] step=${stepNumber} msgs=${totalPendingTokens}/${threshold} obs=${currentObservationTokens}/${effectiveObservationTokensThreshold} bufObs={chunks=${bufferedChunks.length},msgTok=${bufferedMessageTokens},obsTok=${bufferedObservationTokens},status=${obsBufferStatus}} bufRef={inTok=${record.bufferedReflectionInputTokens ?? 0},outTok=${record.bufferedReflectionTokens ?? 0},status=${refBufferStatus}} gen=${record.generationCount}`
+      );
+      await writer.custom(statusPart).catch(() => {
+      });
+    }
+  }
+  /**
+   * Handle observation when threshold is reached.
+   * Tries async activation first if enabled, then falls back to sync observation.
+   * Returns whether observation succeeded.
+   */
+  async handleThresholdReached(messageList, record, threadId, resourceId, threshold, lockKey, writer, abortSignal, abort) {
+    let observationSucceeded = false;
+    let updatedRecord = record;
+    let activatedMessageIds;
+    await this.withLock(lockKey, async () => {
+      let freshRecord = await this.getOrCreateRecord(threadId, resourceId);
+      const freshAllMessages = messageList.get.all.db();
+      let freshUnobservedMessages = this.getUnobservedMessages(freshAllMessages, freshRecord);
+      const freshContextTokens = this.tokenCounter.countMessages(freshAllMessages);
+      let freshOtherThreadTokens = 0;
+      if (this.scope === "resource" && resourceId) {
+        const freshOtherContext = await this.loadOtherThreadsContext(resourceId, threadId);
+        freshOtherThreadTokens = freshOtherContext ? this.tokenCounter.countString(freshOtherContext) : 0;
+      }
+      const freshTotal = freshContextTokens + freshOtherThreadTokens;
+      omDebug(
+        `[OM:threshold] handleThresholdReached (inside lock): freshTotal=${freshTotal}, threshold=${threshold}, freshUnobserved=${freshUnobservedMessages.length}, freshOtherThreadTokens=${freshOtherThreadTokens}, freshCurrentTokens=${freshContextTokens}`
+      );
+      if (freshTotal < threshold) {
+        omDebug(`[OM:threshold] freshTotal < threshold, bailing out`);
+        return;
+      }
+      const preObservationTime = freshRecord.lastObservedAt?.getTime() ?? 0;
+      let activationResult = { success: false };
+      if (this.isAsyncObservationEnabled()) {
+        const bufferKey = this.getObservationBufferKey(lockKey);
+        const asyncOp = _ObservationalMemory.asyncBufferingOps.get(bufferKey);
+        if (asyncOp) {
+          try {
+            await Promise.race([
+              asyncOp,
+              new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 3e4))
+            ]);
+          } catch {
           }
-        });
-        if (observationSucceeded) {
-          const allMsgs = messageList.get.all.db();
-          let markerIdx = -1;
-          let markerMsg = null;
-          for (let i = allMsgs.length - 1; i >= 0; i--) {
-            const msg = allMsgs[i];
-            if (!msg) continue;
-            if (this.findLastCompletedObservationBoundary(msg) !== -1) {
-              markerIdx = i;
-              markerMsg = msg;
-              break;
-            }
+        }
+        const recordAfterWait = await this.getOrCreateRecord(threadId, resourceId);
+        const chunksAfterWait = this.getBufferedChunks(recordAfterWait);
+        omDebug(
+          `[OM:threshold] tryActivation: chunksAvailable=${chunksAfterWait.length}, isBufferingObs=${recordAfterWait.isBufferingObservation}`
+        );
+        activationResult = await this.tryActivateBufferedObservations(
+          recordAfterWait,
+          lockKey,
+          freshTotal,
+          writer,
+          messageList
+        );
+        omDebug(`[OM:threshold] activationResult: success=${activationResult.success}`);
+        if (activationResult.success) {
+          observationSucceeded = true;
+          updatedRecord = activationResult.updatedRecord ?? recordAfterWait;
+          activatedMessageIds = activationResult.activatedMessageIds;
+          omDebug(
+            `[OM:threshold] activation succeeded, obsTokens=${updatedRecord.observationTokenCount}, activeObsLen=${updatedRecord.activeObservations?.length}`
+          );
+          await this.maybeAsyncReflect(updatedRecord, updatedRecord.observationTokenCount ?? 0, writer, messageList);
+          return;
+        }
+        if (this.observationConfig.blockAfter && freshTotal >= this.observationConfig.blockAfter) {
+          omDebug(
+            `[OM:threshold] blockAfter exceeded (${freshTotal} >= ${this.observationConfig.blockAfter}), falling through to sync observation`
+          );
+          freshRecord = await this.getOrCreateRecord(threadId, resourceId);
+          const refreshedAll = messageList.get.all.db();
+          freshUnobservedMessages = this.getUnobservedMessages(refreshedAll, freshRecord);
+        } else {
+          omDebug(`[OM:threshold] activation failed, no blockAfter or below it \u2014 letting async buffering catch up`);
+          return;
+        }
+      }
+      if (freshUnobservedMessages.length > 0) {
+        try {
+          if (this.scope === "resource" && resourceId) {
+            await this.doResourceScopedObservation(
+              freshRecord,
+              threadId,
+              resourceId,
+              freshUnobservedMessages,
+              writer,
+              abortSignal
+            );
+          } else {
+            await this.doSynchronousObservation(freshRecord, threadId, freshUnobservedMessages, writer, abortSignal);
           }
-          if (markerMsg && markerIdx !== -1) {
-            const idsToRemove = [];
-            const messagesToSave = [];
-            for (let i = 0; i < markerIdx; i++) {
-              const msg = allMsgs[i];
-              if (msg?.id && msg.id !== "om-continuation") {
-                idsToRemove.push(msg.id);
-                messagesToSave.push(msg);
-              }
-            }
-            messagesToSave.push(markerMsg);
-            const unobservedParts = this.getUnobservedParts(markerMsg);
-            if (unobservedParts.length === 0) {
-              if (markerMsg.id) {
-                idsToRemove.push(markerMsg.id);
-              }
-            } else if (unobservedParts.length < (markerMsg.content?.parts?.length ?? 0)) {
-              markerMsg.content.parts = unobservedParts;
-            }
-            if (messagesToSave.length > 0) {
-              await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
-            }
-            if (idsToRemove.length > 0) {
-              messageList.removeByIds(idsToRemove);
-            }
+          updatedRecord = await this.getOrCreateRecord(threadId, resourceId);
+          const updatedTime = updatedRecord.lastObservedAt?.getTime() ?? 0;
+          observationSucceeded = updatedTime > preObservationTime;
+        } catch (error) {
+          if (abortSignal?.aborted) {
+            abort("Agent execution was aborted");
           } else {
-            const newInput = messageList.clear.input.db();
-            const newOutput = messageList.clear.response.db();
-            const messagesToSave = [...newInput, ...newOutput];
-            if (messagesToSave.length > 0) {
-              await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
-            }
+            abort(
+              `Encountered error during memory observation ${error instanceof Error ? error.message : JSON.stringify(error, null, 2)}`
+            );
           }
-          messageList.clear.input.db();
-          messageList.clear.response.db();
         }
-        record = await this.getOrCreateRecord(threadId, resourceId);
-      } else if (stepNumber > 0) {
-        const newInput = messageList.clear.input.db();
-        const newOutput = messageList.clear.response.db();
-        const messagesToSave = [...newInput, ...newOutput];
-        if (messagesToSave.length > 0) {
-          await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
-          for (const msg of messagesToSave) {
-            messageList.add(msg, "memory");
-          }
+      }
+    });
+    return { observationSucceeded, updatedRecord, activatedMessageIds };
+  }
+  /**
+   * Remove observed messages from message list after successful observation.
+   * Accepts optional observedMessageIds for activation-based cleanup (when no markers are present).
+   */
+  async cleanupAfterObservation(messageList, sealedIds, threadId, resourceId, state, observedMessageIds) {
+    const allMsgs = messageList.get.all.db();
+    let markerIdx = -1;
+    let markerMsg = null;
+    for (let i = allMsgs.length - 1; i >= 0; i--) {
+      const msg = allMsgs[i];
+      if (!msg) continue;
+      if (this.findLastCompletedObservationBoundary(msg) !== -1) {
+        markerIdx = i;
+        markerMsg = msg;
+        break;
+      }
+    }
+    omDebug(
+      `[OM:cleanupBranch] allMsgs=${allMsgs.length}, markerFound=${markerIdx !== -1}, markerIdx=${markerIdx}, observedMessageIds=${observedMessageIds?.length ?? "undefined"}, allIds=${allMsgs.map((m) => m.id?.slice(0, 8)).join(",")}`
+    );
+    if (markerMsg && markerIdx !== -1) {
+      const idsToRemove = [];
+      const messagesToSave = [];
+      for (let i = 0; i < markerIdx; i++) {
+        const msg = allMsgs[i];
+        if (msg?.id && msg.id !== "om-continuation") {
+          idsToRemove.push(msg.id);
+          messagesToSave.push(msg);
+        }
+      }
+      messagesToSave.push(markerMsg);
+      const unobservedParts = this.getUnobservedParts(markerMsg);
+      if (unobservedParts.length === 0) {
+        if (markerMsg.id) {
+          idsToRemove.push(markerMsg.id);
         }
+      } else if (unobservedParts.length < (markerMsg.content?.parts?.length ?? 0)) {
+        markerMsg.content.parts = unobservedParts;
+      }
+      if (idsToRemove.length > 0) {
+        messageList.removeByIds(idsToRemove);
+      }
+      if (messagesToSave.length > 0) {
+        await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
+      }
+    } else if (observedMessageIds && observedMessageIds.length > 0) {
+      const observedSet = new Set(observedMessageIds);
+      const idsToRemove = [];
+      for (const msg of allMsgs) {
+        if (msg?.id && msg.id !== "om-continuation" && observedSet.has(msg.id)) {
+          idsToRemove.push(msg.id);
+        }
+      }
+      omDebug(
+        `[OM:cleanupActivation] observedSet=${[...observedSet].map((id) => id.slice(0, 8)).join(",")}, matched=${idsToRemove.length}, idsToRemove=${idsToRemove.map((id) => id.slice(0, 8)).join(",")}`
+      );
+      if (idsToRemove.length > 0) {
+        messageList.removeByIds(idsToRemove);
+        omDebug(
+          `[OM:cleanupActivation] removed ${idsToRemove.length} messages, remaining=${messageList.get.all.db().length}`
+        );
+      }
+    } else {
+      const newInput = messageList.clear.input.db();
+      const newOutput = messageList.clear.response.db();
+      const messagesToSave = [...newInput, ...newOutput];
+      if (messagesToSave.length > 0) {
+        await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
+      }
+    }
+    messageList.clear.input.db();
+    messageList.clear.response.db();
+  }
+  /**
+   * Handle per-step save when threshold is not reached.
+   * Persists messages incrementally to prevent data loss on interruption.
+   */
+  async handlePerStepSave(messageList, sealedIds, threadId, resourceId, state) {
+    const newInput = messageList.clear.input.db();
+    const newOutput = messageList.clear.response.db();
+    const messagesToSave = [...newInput, ...newOutput];
+    omDebug(
+      `[OM:handlePerStepSave] cleared input=${newInput.length}, response=${newOutput.length}, toSave=${messagesToSave.length}, ids=${messagesToSave.map((m) => m.id?.slice(0, 8)).join(",")}`
+    );
+    if (messagesToSave.length > 0) {
+      await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
+      for (const msg of messagesToSave) {
+        messageList.add(msg, "memory");
       }
     }
+  }
+  /**
+   * Inject observations as system message and add continuation reminder.
+   */
+  async injectObservationsIntoContext(messageList, record, threadId, resourceId, unobservedContextBlocks, requestContext) {
     const thread = await this.storage.getThreadById({ threadId });
     const threadOMMetadata = memory.getThreadOMMetadata(thread?.metadata);
     const currentTask = threadOMMetadata?.currentTask;
     const suggestedResponse = threadOMMetadata?.suggestedResponse;
-    const currentDate = requestContext?.get("currentDate") ?? /* @__PURE__ */ new Date();
-    if (record.activeObservations) {
-      const observationSystemMessage = this.formatObservationsForContext(
-        record.activeObservations,
-        currentTask,
-        suggestedResponse,
-        unobservedContextBlocks,
-        currentDate
-      );
-      messageList.clearSystemMessages("observational-memory");
-      messageList.addSystem(observationSystemMessage, "observational-memory");
-      const continuationMessage = {
-        id: `om-continuation`,
-        role: "user",
-        createdAt: /* @__PURE__ */ new Date(0),
-        content: {
-          format: 2,
-          parts: [
-            {
-              type: "text",
-              text: `<system-reminder>This message is not from the user, the conversation history grew too long and wouldn't fit in context! Thankfully the entire conversation is stored in your memory observations. Please continue from where the observations left off. Do not refer to your "memory observations" directly, the user doesn't know about them, they are your memories! Just respond naturally as if you're remembering the conversation (you are!). Do not say "Hi there!" or "based on our previous conversation" as if the conversation is just starting, this is not a new conversation. This is an ongoing conversation, keep continuity by responding based on your memory. For example do not say "I understand. I've reviewed my memory observations", or "I remember [...]". Answer naturally following the suggestion from your memory. Note that your memory may contain a suggested first response, which you should follow.
+    const rawCurrentDate = requestContext?.get("currentDate");
+    const currentDate = rawCurrentDate instanceof Date ? rawCurrentDate : typeof rawCurrentDate === "string" ? new Date(rawCurrentDate) : /* @__PURE__ */ new Date();
+    if (!record.activeObservations) {
+      return;
+    }
+    const observationSystemMessage = this.formatObservationsForContext(
+      record.activeObservations,
+      currentTask,
+      suggestedResponse,
+      unobservedContextBlocks,
+      currentDate
+    );
+    messageList.clearSystemMessages("observational-memory");
+    messageList.addSystem(observationSystemMessage, "observational-memory");
+    const continuationMessage = {
+      id: `om-continuation`,
+      role: "user",
+      createdAt: /* @__PURE__ */ new Date(0),
+      content: {
+        format: 2,
+        parts: [
+          {
+            type: "text",
+            text: `<system-reminder>This message is not from the user, the conversation history grew too long and wouldn't fit in context! Thankfully the entire conversation is stored in your memory observations. Please continue from where the observations left off. Do not refer to your "memory observations" directly, the user doesn't know about them, they are your memories! Just respond naturally as if you're remembering the conversation (you are!). Do not say "Hi there!" or "based on our previous conversation" as if the conversation is just starting, this is not a new conversation. This is an ongoing conversation, keep continuity by responding based on your memory. For example do not say "I understand. I've reviewed my memory observations", or "I remember [...]". Answer naturally following the suggestion from your memory. Note that your memory may contain a suggested first response, which you should follow.
 
 IMPORTANT: this system reminder is NOT from the user. The system placed it here as part of your memory system. This message is part of you remembering your conversation with the user.
 
 NOTE: Any messages following this system reminder are newer than your memories.
 </system-reminder>`
-            }
-          ]
-        },
-        threadId,
-        resourceId
-      };
-      messageList.add(continuationMessage, "memory");
+          }
+        ]
+      },
+      threadId,
+      resourceId
+    };
+    messageList.add(continuationMessage, "memory");
+  }
+  /**
+   * Filter out already-observed messages from message list (step 0 only).
+   * Historical messages loaded from DB may contain observation markers from previous sessions.
+   */
+  filterAlreadyObservedMessages(messageList, record) {
+    const allMessages = messageList.get.all.db();
+    let markerMessageIndex = -1;
+    let markerMessage = null;
+    for (let i = allMessages.length - 1; i >= 0; i--) {
+      const msg = allMessages[i];
+      if (!msg) continue;
+      if (this.findLastCompletedObservationBoundary(msg) !== -1) {
+        markerMessageIndex = i;
+        markerMessage = msg;
+        break;
+      }
     }
-    if (stepNumber === 0) {
-      const allMessages = messageList.get.all.db();
-      let markerMessageIndex = -1;
-      let markerMessage = null;
-      for (let i = allMessages.length - 1; i >= 0; i--) {
+    if (markerMessage && markerMessageIndex !== -1) {
+      const messagesToRemove = [];
+      for (let i = 0; i < markerMessageIndex; i++) {
         const msg = allMessages[i];
-        if (!msg) continue;
-        if (this.findLastCompletedObservationBoundary(msg) !== -1) {
-          markerMessageIndex = i;
-          markerMessage = msg;
-          break;
+        if (msg?.id && msg.id !== "om-continuation") {
+          messagesToRemove.push(msg.id);
         }
       }
-      if (markerMessage && markerMessageIndex !== -1) {
-        const messagesToRemove = [];
-        for (let i = 0; i < markerMessageIndex; i++) {
-          const msg = allMessages[i];
-          if (msg?.id && msg.id !== "om-continuation") {
+      if (messagesToRemove.length > 0) {
+        messageList.removeByIds(messagesToRemove);
+      }
+      const unobservedParts = this.getUnobservedParts(markerMessage);
+      if (unobservedParts.length === 0) {
+        if (markerMessage.id) {
+          messageList.removeByIds([markerMessage.id]);
+        }
+      } else if (unobservedParts.length < (markerMessage.content?.parts?.length ?? 0)) {
+        markerMessage.content.parts = unobservedParts;
+      }
+    } else if (record) {
+      const observedIds = new Set(Array.isArray(record.observedMessageIds) ? record.observedMessageIds : []);
+      const lastObservedAt = record.lastObservedAt;
+      const messagesToRemove = [];
+      for (const msg of allMessages) {
+        if (!msg?.id || msg.id === "om-continuation") continue;
+        if (observedIds.has(msg.id)) {
+          messagesToRemove.push(msg.id);
+          continue;
+        }
+        if (lastObservedAt && msg.createdAt) {
+          const msgDate = new Date(msg.createdAt);
+          if (msgDate <= lastObservedAt) {
             messagesToRemove.push(msg.id);
           }
         }
-        if (messagesToRemove.length > 0) {
-          messageList.removeByIds(messagesToRemove);
+      }
+      if (messagesToRemove.length > 0) {
+        messageList.removeByIds(messagesToRemove);
+      }
+    }
+  }
+  /**
+   * Process input at each step - check threshold, observe if needed, save, inject observations.
+   * This is the ONLY processor method - all OM logic happens here.
+   *
+   * Flow:
+   * 1. Load historical messages (step 0 only)
+   * 2. Check if observation threshold is reached
+   * 3. If threshold reached: observe, save messages with markers
+   * 4. Inject observations into context
+   * 5. Filter out already-observed messages
+   */
+  async processInputStep(args) {
+    const { messageList, requestContext, stepNumber, state: _state, writer, abortSignal, abort } = args;
+    const state = _state ?? {};
+    const context = this.getThreadContext(requestContext, messageList);
+    if (!context) {
+      return messageList;
+    }
+    const { threadId, resourceId } = context;
+    const memoryContext = memory.parseMemoryRequestContext(requestContext);
+    const readOnly = memoryContext?.memoryConfig?.readOnly;
+    let record = await this.getOrCreateRecord(threadId, resourceId);
+    omDebug(
+      `[OM:step] processInputStep step=${stepNumber}: recordId=${record.id}, genCount=${record.generationCount}, obsTokens=${record.observationTokenCount}, bufferedReflection=${record.bufferedReflection ? "present (" + record.bufferedReflection.length + " chars)" : "empty"}, activeObsLen=${record.activeObservations?.length}`
+    );
+    await this.loadHistoricalMessagesIfNeeded(messageList, state, threadId, resourceId, record.lastObservedAt);
+    let unobservedContextBlocks;
+    if (this.scope === "resource" && resourceId) {
+      unobservedContextBlocks = await this.loadOtherThreadsContext(resourceId, threadId);
+    }
+    if (stepNumber === 0 && !readOnly && this.isAsyncObservationEnabled()) {
+      const lockKey = this.getLockKey(threadId, resourceId);
+      const bufferedChunks = this.getBufferedChunks(record);
+      omDebug(
+        `[OM:step0-activation] asyncObsEnabled=true, bufferedChunks=${bufferedChunks.length}, isBufferingObs=${record.isBufferingObservation}`
+      );
+      {
+        const bufKey = this.getObservationBufferKey(lockKey);
+        const dbBoundary = record.lastBufferedAtTokens ?? 0;
+        const currentContextTokens = this.tokenCounter.countMessages(messageList.get.all.db());
+        if (dbBoundary > currentContextTokens) {
+          omDebug(
+            `[OM:step0-boundary-reset] dbBoundary=${dbBoundary} > currentContext=${currentContextTokens}, resetting to current`
+          );
+          _ObservationalMemory.lastBufferedBoundary.set(bufKey, currentContextTokens);
+          this.storage.setBufferingObservationFlag(record.id, false, currentContextTokens).catch(() => {
+          });
+        }
+      }
+      if (bufferedChunks.length > 0) {
+        const allMsgsForCheck = messageList.get.all.db();
+        const otherThreadTokensForCheck = unobservedContextBlocks ? this.tokenCounter.countString(unobservedContextBlocks) : 0;
+        const currentObsTokensForCheck = record.observationTokenCount ?? 0;
+        const { totalPendingTokens: step0PendingTokens, threshold: step0Threshold } = this.calculateObservationThresholds(
+          allMsgsForCheck,
+          [],
+          // unobserved not needed for threshold calculation
+          0,
+          // pendingTokens not needed — allMessages covers context
+          otherThreadTokensForCheck,
+          currentObsTokensForCheck,
+          record
+        );
+        omDebug(
+          `[OM:step0-activation] pendingTokens=${step0PendingTokens}, threshold=${step0Threshold}, blockAfter=${this.observationConfig.blockAfter}, shouldActivate=${step0PendingTokens >= step0Threshold}, allMsgs=${allMsgsForCheck.length}`
+        );
+        if (step0PendingTokens >= step0Threshold) {
+          const activationResult = await this.tryActivateBufferedObservations(
+            record,
+            lockKey,
+            step0PendingTokens,
+            writer,
+            messageList
+          );
+          if (activationResult.success && activationResult.updatedRecord) {
+            record = activationResult.updatedRecord;
+            const activatedIds = activationResult.activatedMessageIds ?? [];
+            if (activatedIds.length > 0) {
+              const activatedSet = new Set(activatedIds);
+              const allMsgs = messageList.get.all.db();
+              const idsToRemove = allMsgs.filter((msg) => msg?.id && msg.id !== "om-continuation" && activatedSet.has(msg.id)).map((msg) => msg.id);
+              if (idsToRemove.length > 0) {
+                messageList.removeByIds(idsToRemove);
+              }
+            }
+            this.cleanupStaticMaps(threadId, resourceId, activatedIds);
+            const bufKey = this.getObservationBufferKey(lockKey);
+            _ObservationalMemory.lastBufferedBoundary.set(bufKey, 0);
+            this.storage.setBufferingObservationFlag(record.id, false, 0).catch(() => {
+            });
+            await this.maybeReflect(
+              record,
+              record.observationTokenCount ?? 0,
+              threadId,
+              writer,
+              void 0,
+              messageList
+            );
+            record = await this.getOrCreateRecord(threadId, resourceId);
+          }
+        }
+      }
+    }
+    if (stepNumber === 0 && !readOnly) {
+      const obsTokens = record.observationTokenCount ?? 0;
+      if (this.shouldReflect(obsTokens)) {
+        omDebug(`[OM:step0-reflect] obsTokens=${obsTokens} over reflectThreshold, triggering reflection`);
+        await this.maybeReflect(record, obsTokens, threadId, writer, void 0, messageList);
+        record = await this.getOrCreateRecord(threadId, resourceId);
+      } else if (this.isAsyncReflectionEnabled()) {
+        const lockKey = this.getLockKey(threadId, resourceId);
+        if (this.shouldTriggerAsyncReflection(obsTokens, lockKey, record)) {
+          omDebug(`[OM:step0-reflect] obsTokens=${obsTokens} above activation point, triggering async reflection`);
+          await this.maybeAsyncReflect(record, obsTokens, writer, messageList);
+          record = await this.getOrCreateRecord(threadId, resourceId);
+        }
+      }
+    }
+    if (!readOnly) {
+      const allMessages = messageList.get.all.db();
+      const unobservedMessages = this.getUnobservedMessages(allMessages, record);
+      const otherThreadTokens = unobservedContextBlocks ? this.tokenCounter.countString(unobservedContextBlocks) : 0;
+      const currentObservationTokens = record.observationTokenCount ?? 0;
+      const thresholds = this.calculateObservationThresholds(
+        allMessages,
+        unobservedMessages,
+        0,
+        // pendingTokens not needed — allMessages covers context
+        otherThreadTokens,
+        currentObservationTokens,
+        record
+      );
+      const { totalPendingTokens, threshold } = thresholds;
+      const stateSealedIds = state.sealedIds ?? /* @__PURE__ */ new Set();
+      const staticSealedIds = _ObservationalMemory.sealedMessageIds.get(threadId) ?? /* @__PURE__ */ new Set();
+      const sealedIds = /* @__PURE__ */ new Set([...stateSealedIds, ...staticSealedIds]);
+      state.sealedIds = sealedIds;
+      const lockKey = this.getLockKey(threadId, resourceId);
+      if (this.isAsyncObservationEnabled() && totalPendingTokens < threshold) {
+        const shouldTrigger = this.shouldTriggerAsyncObservation(totalPendingTokens, lockKey, record);
+        omDebug(
+          `[OM:async-obs] belowThreshold: pending=${totalPendingTokens}, threshold=${threshold}, shouldTrigger=${shouldTrigger}, isBufferingObs=${record.isBufferingObservation}, lastBufferedAt=${record.lastBufferedAtTokens}`
+        );
+        if (shouldTrigger) {
+          this.startAsyncBufferedObservation(record, threadId, unobservedMessages, lockKey, writer, totalPendingTokens);
+        }
+      } else if (this.isAsyncObservationEnabled()) {
+        const shouldTrigger = this.shouldTriggerAsyncObservation(totalPendingTokens, lockKey, record);
+        omDebug(
+          `[OM:async-obs] atOrAboveThreshold: pending=${totalPendingTokens}, threshold=${threshold}, step=${stepNumber}, shouldTrigger=${shouldTrigger}`
+        );
+        if (shouldTrigger) {
+          this.startAsyncBufferedObservation(record, threadId, unobservedMessages, lockKey, writer, totalPendingTokens);
         }
-        const unobservedParts = this.getUnobservedParts(markerMessage);
-        if (unobservedParts.length === 0) {
-          if (markerMessage.id) {
-            messageList.removeByIds([markerMessage.id]);
+      }
+      if (stepNumber > 0) {
+        await this.handlePerStepSave(messageList, sealedIds, threadId, resourceId, state);
+      }
+      if (stepNumber > 0 && totalPendingTokens >= threshold) {
+        const { observationSucceeded, updatedRecord, activatedMessageIds } = await this.handleThresholdReached(
+          messageList,
+          record,
+          threadId,
+          resourceId,
+          threshold,
+          lockKey,
+          writer,
+          abortSignal,
+          abort
+        );
+        if (observationSucceeded) {
+          const observedIds = activatedMessageIds?.length ? activatedMessageIds : Array.isArray(updatedRecord.observedMessageIds) ? updatedRecord.observedMessageIds : void 0;
+          omDebug(
+            `[OM:cleanup] observedIds=${observedIds?.length ?? "undefined"}, ids=${observedIds?.join(",") ?? "none"}, updatedRecord.observedMessageIds=${JSON.stringify(updatedRecord.observedMessageIds)}`
+          );
+          await this.cleanupAfterObservation(messageList, sealedIds, threadId, resourceId, state, observedIds);
+          if (activatedMessageIds?.length) {
+            this.cleanupStaticMaps(threadId, resourceId, activatedMessageIds);
+          }
+          if (this.isAsyncObservationEnabled()) {
+            const bufKey = this.getObservationBufferKey(lockKey);
+            _ObservationalMemory.lastBufferedBoundary.set(bufKey, 0);
+            this.storage.setBufferingObservationFlag(updatedRecord.id, false, 0).catch(() => {
+            });
+            omDebug(`[OM:threshold] post-activation boundary reset to 0`);
           }
-        } else if (unobservedParts.length < (markerMessage.content?.parts?.length ?? 0)) {
-          markerMessage.content.parts = unobservedParts;
         }
+        record = updatedRecord;
       }
     }
+    await this.injectObservationsIntoContext(
+      messageList,
+      record,
+      threadId,
+      resourceId,
+      unobservedContextBlocks,
+      requestContext
+    );
+    if (stepNumber === 0) {
+      this.filterAlreadyObservedMessages(messageList, record);
+    }
+    {
+      const freshRecord = await this.getOrCreateRecord(threadId, resourceId);
+      const contextMessages = messageList.get.all.db();
+      const freshUnobservedTokens = this.tokenCounter.countMessages(contextMessages);
+      const otherThreadTokens = unobservedContextBlocks ? this.tokenCounter.countString(unobservedContextBlocks) : 0;
+      const currentObservationTokens = freshRecord.observationTokenCount ?? 0;
+      const threshold = this.calculateDynamicThreshold(this.observationConfig.messageTokens, currentObservationTokens);
+      const baseReflectionThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+      const isSharedBudget = typeof this.observationConfig.messageTokens !== "number";
+      const totalBudget = isSharedBudget ? this.observationConfig.messageTokens.max : 0;
+      const effectiveObservationTokensThreshold = isSharedBudget ? Math.max(totalBudget - threshold, 1e3) : baseReflectionThreshold;
+      const totalPendingTokens = freshUnobservedTokens + otherThreadTokens;
+      await this.emitStepProgress(
+        writer,
+        threadId,
+        resourceId,
+        stepNumber,
+        freshRecord,
+        {
+          totalPendingTokens,
+          threshold,
+          effectiveObservationTokensThreshold
+        },
+        currentObservationTokens
+      );
+    }
     return messageList;
   }
   /**
@@ -2303,11 +3277,21 @@ NOTE: Any messages following this system reminder are newer than your memories.
     const newInput = messageList.get.input.db();
     const newOutput = messageList.get.response.db();
     const messagesToSave = [...newInput, ...newOutput];
+    omDebug(
+      `[OM:processOutputResult] threadId=${threadId}, inputMsgs=${newInput.length}, responseMsgs=${newOutput.length}, totalToSave=${messagesToSave.length}, allMsgsInList=${messageList.get.all.db().length}`
+    );
     if (messagesToSave.length === 0) {
+      omDebug(`[OM:processOutputResult] nothing to save \u2014 all messages were already saved during per-step saves`);
       return messageList;
     }
     const sealedIds = state.sealedIds ?? /* @__PURE__ */ new Set();
+    omDebug(
+      `[OM:processOutputResult] saving ${messagesToSave.length} messages, sealedIds=${sealedIds.size}, ids=${messagesToSave.map((m) => m.id?.slice(0, 8)).join(",")}`
+    );
     await this.saveMessagesWithSealedIdTracking(messagesToSave, sealedIds, threadId, resourceId, state);
+    omDebug(
+      `[OM:processOutputResult] saved successfully, finalIds=${messagesToSave.map((m) => m.id?.slice(0, 8)).join(",")}`
+    );
     return messageList;
   }
   /**
@@ -2537,6 +3521,7 @@ ${newThreadSection}`;
       }))
     });
     await this.storage.setObservingFlag(record.id, true);
+    registerOp(record.id, "observing");
     const cycleId = crypto.randomUUID();
     const tokensToObserve = this.tokenCounter.countMessages(unobservedMessages);
     const lastMessage = unobservedMessages[unobservedMessages.length - 1];
@@ -2562,9 +3547,20 @@ ${newThreadSection}`;
           return;
         }
       }
+      let messagesToObserve = unobservedMessages;
+      const bufferActivation = this.observationConfig.bufferActivation;
+      if (bufferActivation && bufferActivation < 1 && unobservedMessages.length >= 1) {
+        const newestMsg = unobservedMessages[unobservedMessages.length - 1];
+        if (newestMsg?.content?.parts?.length) {
+          this.sealMessagesForBuffering([newestMsg]);
+          omDebug(
+            `[OM:sync-obs] sealed newest message (${newestMsg.role}, ${newestMsg.content.parts.length} parts) for ratio-aware observation`
+          );
+        }
+      }
       const result = await this.callObserver(
         freshRecord?.activeObservations ?? record.activeObservations,
-        unobservedMessages,
+        messagesToObserve,
         abortSignal
       );
       const existingObservations = freshRecord?.activeObservations ?? record.activeObservations ?? "";
@@ -2579,8 +3575,8 @@ ${result.observations}` : result.observations;
       }
       let totalTokenCount = this.tokenCounter.countObservations(newObservations);
       const cycleObservationTokens = this.tokenCounter.countObservations(result.observations);
-      const lastObservedAt = this.getMaxMessageTimestamp(unobservedMessages);
-      const newMessageIds = unobservedMessages.map((m) => m.id);
+      const lastObservedAt = this.getMaxMessageTimestamp(messagesToObserve);
+      const newMessageIds = messagesToObserve.map((m) => m.id);
       const existingIds = freshRecord?.observedMessageIds ?? record.observedMessageIds ?? [];
       const allObservedIds = [.../* @__PURE__ */ new Set([...Array.isArray(existingIds) ? existingIds : [], ...newMessageIds])];
       await this.storage.updateActiveObservations({
@@ -2604,12 +3600,13 @@ ${result.observations}` : result.observations;
           });
         }
       }
+      const actualTokensObserved = this.tokenCounter.countMessages(messagesToObserve);
       if (lastMessage?.id) {
         const endMarker = this.createObservationEndMarker({
           cycleId,
           operationType: "observation",
           startedAt,
-          tokensObserved: tokensToObserve,
+          tokensObserved: actualTokensObserved,
           observationTokens: cycleObservationTokens,
           observations: result.observations,
           currentTask: result.currentTask,
@@ -2630,7 +3627,7 @@ ${result.observations}` : result.observations;
         observations: newObservations,
         rawObserverOutput: result.observations,
         previousObservations: record.activeObservations,
-        messages: unobservedMessages.map((m) => ({
+        messages: messagesToObserve.map((m) => ({
           role: m.role,
           content: typeof m.content === "string" ? m.content : JSON.stringify(m.content)
         })),
@@ -2662,11 +3659,514 @@ ${result.observations}` : result.observations;
       if (abortSignal?.aborted) {
         throw error;
       }
-      console.error(`[OM] Observation failed:`, error instanceof Error ? error.message : String(error));
+      omError("[OM] Observation failed", error);
     } finally {
       await this.storage.setObservingFlag(record.id, false);
+      unregisterOp(record.id, "observing");
     }
   }
+  /**
+   * Start an async background observation that stores results to bufferedObservations.
+   * This is a fire-and-forget operation that runs in the background.
+   * The results will be swapped to active when the main threshold is reached.
+   *
+   * If another buffering operation is already in progress for this scope, this will
+   * wait for it to complete before starting a new one (mutex behavior).
+   *
+   * @param record - Current OM record
+   * @param threadId - Thread ID
+   * @param unobservedMessages - All unobserved messages (will be filtered for already-buffered)
+   * @param lockKey - Lock key for this scope
+   * @param writer - Optional stream writer for emitting buffering markers
+   */
+  startAsyncBufferedObservation(record, threadId, unobservedMessages, lockKey, writer, contextWindowTokens) {
+    const bufferKey = this.getObservationBufferKey(lockKey);
+    const currentTokens = contextWindowTokens ?? this.tokenCounter.countMessages(unobservedMessages) + (record.pendingMessageTokens ?? 0);
+    _ObservationalMemory.lastBufferedBoundary.set(bufferKey, currentTokens);
+    registerOp(record.id, "bufferingObservation");
+    this.storage.setBufferingObservationFlag(record.id, true, currentTokens).catch((err) => {
+      omError("[OM] Failed to set buffering observation flag", err);
+    });
+    const asyncOp = this.runAsyncBufferedObservation(record, threadId, unobservedMessages, bufferKey, writer).finally(
+      () => {
+        _ObservationalMemory.asyncBufferingOps.delete(bufferKey);
+        unregisterOp(record.id, "bufferingObservation");
+        this.storage.setBufferingObservationFlag(record.id, false).catch((err) => {
+          omError("[OM] Failed to clear buffering observation flag", err);
+        });
+      }
+    );
+    _ObservationalMemory.asyncBufferingOps.set(bufferKey, asyncOp);
+  }
+  /**
+   * Internal method that waits for existing buffering operation and then runs new buffering.
+   * This implements the mutex-wait behavior.
+   */
+  async runAsyncBufferedObservation(record, threadId, unobservedMessages, bufferKey, writer) {
+    const existingOp = _ObservationalMemory.asyncBufferingOps.get(bufferKey);
+    if (existingOp) {
+      try {
+        await existingOp;
+      } catch {
+      }
+    }
+    const freshRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+    if (!freshRecord) {
+      return;
+    }
+    let bufferCursor = _ObservationalMemory.lastBufferedAtTime.get(bufferKey) ?? freshRecord.lastBufferedAtTime ?? null;
+    if (freshRecord.lastObservedAt) {
+      const lastObserved = new Date(freshRecord.lastObservedAt);
+      if (!bufferCursor || lastObserved > bufferCursor) {
+        bufferCursor = lastObserved;
+      }
+    }
+    let candidateMessages = this.getUnobservedMessages(unobservedMessages, freshRecord, {
+      excludeBuffered: true
+    });
+    const preFilterCount = candidateMessages.length;
+    if (bufferCursor) {
+      candidateMessages = candidateMessages.filter((msg) => {
+        if (!msg.createdAt) return true;
+        return new Date(msg.createdAt) > bufferCursor;
+      });
+    }
+    omDebug(
+      `[OM:bufferCursor] cursor=${bufferCursor?.toISOString() ?? "null"}, unobserved=${unobservedMessages.length}, afterExcludeBuffered=${preFilterCount}, afterCursorFilter=${candidateMessages.length}`
+    );
+    const bufferTokens = this.observationConfig.bufferTokens ?? 5e3;
+    const minNewTokens = bufferTokens / 2;
+    const newTokens = this.tokenCounter.countMessages(candidateMessages);
+    if (newTokens < minNewTokens) {
+      return;
+    }
+    const messagesToBuffer = candidateMessages;
+    this.sealMessagesForBuffering(messagesToBuffer);
+    await this.messageHistory.persistMessages({
+      messages: messagesToBuffer,
+      threadId,
+      resourceId: freshRecord.resourceId ?? void 0
+    });
+    let staticSealedIds = _ObservationalMemory.sealedMessageIds.get(threadId);
+    if (!staticSealedIds) {
+      staticSealedIds = /* @__PURE__ */ new Set();
+      _ObservationalMemory.sealedMessageIds.set(threadId, staticSealedIds);
+    }
+    for (const msg of messagesToBuffer) {
+      staticSealedIds.add(msg.id);
+    }
+    const cycleId = `buffer-obs-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const tokensToBuffer = this.tokenCounter.countMessages(messagesToBuffer);
+    if (writer) {
+      const startMarker = this.createBufferingStartMarker({
+        cycleId,
+        operationType: "observation",
+        tokensToBuffer,
+        recordId: freshRecord.id,
+        threadId,
+        threadIds: [threadId]
+      });
+      void writer.custom(startMarker).catch(() => {
+      });
+    }
+    try {
+      omDebug(
+        `[OM:bufferInput] cycleId=${cycleId}, msgCount=${messagesToBuffer.length}, msgTokens=${this.tokenCounter.countMessages(messagesToBuffer)}, ids=${messagesToBuffer.map((m) => `${m.id?.slice(0, 8)}@${m.createdAt ? new Date(m.createdAt).toISOString() : "none"}`).join(",")}`
+      );
+      await this.doAsyncBufferedObservation(freshRecord, threadId, messagesToBuffer, cycleId, startedAt, writer);
+      const maxTs = this.getMaxMessageTimestamp(messagesToBuffer);
+      const cursor = new Date(maxTs.getTime() + 1);
+      _ObservationalMemory.lastBufferedAtTime.set(bufferKey, cursor);
+    } catch (error) {
+      if (writer) {
+        const failedMarker = this.createBufferingFailedMarker({
+          cycleId,
+          operationType: "observation",
+          startedAt,
+          tokensAttempted: tokensToBuffer,
+          error: error instanceof Error ? error.message : String(error),
+          recordId: freshRecord.id,
+          threadId
+        });
+        void writer.custom(failedMarker).catch(() => {
+        });
+      }
+      omError("[OM] Async buffered observation failed", error);
+    }
+  }
+  /**
+   * Perform async buffered observation - observes messages and stores to bufferedObservations.
+   * Does NOT update activeObservations or trigger reflection.
+   *
+   * The observer sees: active observations + existing buffered observations + message history
+   * (excluding already-buffered messages).
+   */
+  async doAsyncBufferedObservation(record, threadId, messagesToBuffer, cycleId, startedAt, writer) {
+    const bufferedChunks = this.getBufferedChunks(record);
+    const bufferedChunksText = bufferedChunks.map((c) => c.observations).join("\n\n");
+    const combinedObservations = this.combineObservationsForBuffering(record.activeObservations, bufferedChunksText);
+    const result = await this.callObserver(
+      combinedObservations,
+      messagesToBuffer,
+      void 0,
+      // No abort signal for background ops
+      { skipContinuationHints: true }
+    );
+    let newObservations;
+    if (this.scope === "resource") {
+      newObservations = await this.wrapWithThreadTag(threadId, result.observations);
+    } else {
+      newObservations = result.observations;
+    }
+    const newTokenCount = this.tokenCounter.countObservations(newObservations);
+    const newMessageIds = messagesToBuffer.map((m) => m.id);
+    const messageTokens = this.tokenCounter.countMessages(messagesToBuffer);
+    const maxMessageTimestamp = this.getMaxMessageTimestamp(messagesToBuffer);
+    const lastObservedAt = new Date(maxMessageTimestamp.getTime() + 1);
+    await this.storage.updateBufferedObservations({
+      id: record.id,
+      chunk: {
+        cycleId,
+        observations: newObservations,
+        tokenCount: newTokenCount,
+        messageIds: newMessageIds,
+        messageTokens,
+        lastObservedAt
+      },
+      lastBufferedAtTime: lastObservedAt
+    });
+    if (writer) {
+      const tokensBuffered = this.tokenCounter.countMessages(messagesToBuffer);
+      const updatedRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+      const updatedChunks = this.getBufferedChunks(updatedRecord);
+      const totalBufferedTokens = updatedChunks.reduce((sum, c) => sum + (c.tokenCount ?? 0), 0) || newTokenCount;
+      const endMarker = this.createBufferingEndMarker({
+        cycleId,
+        operationType: "observation",
+        startedAt,
+        tokensBuffered,
+        bufferedTokens: totalBufferedTokens,
+        recordId: record.id,
+        threadId,
+        observations: newObservations
+      });
+      void writer.custom(endMarker).catch(() => {
+      });
+    }
+  }
+  /**
+   * Combine active and buffered observations for the buffering observer context.
+   * The buffering observer needs to see both so it doesn't duplicate content.
+   */
+  combineObservationsForBuffering(activeObservations, bufferedObservations) {
+    if (!activeObservations && !bufferedObservations) {
+      return void 0;
+    }
+    if (!activeObservations) {
+      return bufferedObservations;
+    }
+    if (!bufferedObservations) {
+      return activeObservations;
+    }
+    return `${activeObservations}
+
+--- BUFFERED (pending activation) ---
+
+${bufferedObservations}`;
+  }
+  /**
+   * Try to activate buffered observations when threshold is reached.
+   * Returns true if activation succeeded, false if no buffered content or activation failed.
+   *
+   * @param record - Current OM record
+   * @param lockKey - Lock key for this scope
+   * @param writer - Optional writer for emitting UI markers
+   */
+  async tryActivateBufferedObservations(record, lockKey, currentPendingTokens, writer, messageList) {
+    const chunks = this.getBufferedChunks(record);
+    omDebug(`[OM:tryActivate] chunks=${chunks.length}, recordId=${record.id}`);
+    if (!chunks.length) {
+      omDebug(`[OM:tryActivate] no chunks, returning false`);
+      return { success: false };
+    }
+    const bufferKey = this.getObservationBufferKey(lockKey);
+    const asyncOp = _ObservationalMemory.asyncBufferingOps.get(bufferKey);
+    if (asyncOp) {
+      try {
+        await Promise.race([
+          asyncOp,
+          new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 6e4))
+        ]);
+      } catch {
+      }
+    }
+    const freshRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+    if (!freshRecord) {
+      return { success: false };
+    }
+    const freshChunks = this.getBufferedChunks(freshRecord);
+    if (!freshChunks.length) {
+      return { success: false };
+    }
+    const activationRatio = this.observationConfig.bufferActivation ?? 0.7;
+    omDebug(
+      `[OM:tryActivate] swapping: freshChunks=${freshChunks.length}, activationRatio=${activationRatio}, totalChunkTokens=${freshChunks.reduce((s, c) => s + (c.tokenCount ?? 0), 0)}`
+    );
+    const messageTokensThreshold = this.getMaxThreshold(this.observationConfig.messageTokens);
+    const activationResult = await this.storage.swapBufferedToActive({
+      id: freshRecord.id,
+      activationRatio,
+      messageTokensThreshold,
+      currentPendingTokens
+    });
+    omDebug(
+      `[OM:tryActivate] swapResult: chunksActivated=${activationResult.chunksActivated}, tokensActivated=${activationResult.messageTokensActivated}, obsTokensActivated=${activationResult.observationTokensActivated}, activatedCycleIds=${activationResult.activatedCycleIds.join(",")}`
+    );
+    await this.storage.setBufferingObservationFlag(freshRecord.id, false);
+    unregisterOp(freshRecord.id, "bufferingObservation");
+    const updatedRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+    if (writer && updatedRecord && activationResult.activatedCycleIds.length > 0) {
+      const perChunkMap = new Map(activationResult.perChunk?.map((c) => [c.cycleId, c]));
+      for (const cycleId of activationResult.activatedCycleIds) {
+        const chunkData = perChunkMap.get(cycleId);
+        const activationMarker = this.createActivationMarker({
+          cycleId,
+          // Use the original buffering cycleId so UI can link them
+          operationType: "observation",
+          chunksActivated: 1,
+          tokensActivated: chunkData?.messageTokens ?? activationResult.messageTokensActivated,
+          observationTokens: chunkData?.observationTokens ?? activationResult.observationTokensActivated,
+          messagesActivated: chunkData?.messageCount ?? activationResult.messagesActivated,
+          recordId: updatedRecord.id,
+          threadId: updatedRecord.threadId ?? record.threadId ?? "",
+          generationCount: updatedRecord.generationCount ?? 0,
+          observations: chunkData?.observations ?? activationResult.observations
+        });
+        void writer.custom(activationMarker).catch(() => {
+        });
+        await this.persistMarkerToMessage(
+          activationMarker,
+          messageList,
+          record.threadId ?? "",
+          record.resourceId ?? void 0
+        );
+      }
+    }
+    return {
+      success: true,
+      updatedRecord: updatedRecord ?? void 0,
+      messageTokensActivated: activationResult.messageTokensActivated,
+      activatedMessageIds: activationResult.activatedMessageIds
+    };
+  }
+  /**
+   * Start an async background reflection that stores results to bufferedReflection.
+   * This is a fire-and-forget operation that runs in the background.
+   * The results will be swapped to active when the main reflection threshold is reached.
+   *
+   * @param record - Current OM record
+   * @param observationTokens - Current observation token count
+   * @param lockKey - Lock key for this scope
+   */
+  startAsyncBufferedReflection(record, observationTokens, lockKey, writer) {
+    const bufferKey = this.getReflectionBufferKey(lockKey);
+    if (this.isAsyncBufferingInProgress(bufferKey)) {
+      return;
+    }
+    _ObservationalMemory.lastBufferedBoundary.set(bufferKey, observationTokens);
+    registerOp(record.id, "bufferingReflection");
+    this.storage.setBufferingReflectionFlag(record.id, true).catch((err) => {
+      omError("[OM] Failed to set buffering reflection flag", err);
+    });
+    const asyncOp = this.doAsyncBufferedReflection(record, bufferKey, writer).catch((error) => {
+      if (writer) {
+        const failedMarker = this.createBufferingFailedMarker({
+          cycleId: `reflect-buf-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+          operationType: "reflection",
+          startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          tokensAttempted: observationTokens,
+          error: error instanceof Error ? error.message : String(error),
+          recordId: record.id,
+          threadId: record.threadId ?? ""
+        });
+        void writer.custom(failedMarker).catch(() => {
+        });
+      }
+      omError("[OM] Async buffered reflection failed", error);
+    }).finally(() => {
+      _ObservationalMemory.asyncBufferingOps.delete(bufferKey);
+      unregisterOp(record.id, "bufferingReflection");
+      this.storage.setBufferingReflectionFlag(record.id, false).catch((err) => {
+        omError("[OM] Failed to clear buffering reflection flag", err);
+      });
+    });
+    _ObservationalMemory.asyncBufferingOps.set(bufferKey, asyncOp);
+  }
+  /**
+   * Perform async buffered reflection - reflects observations and stores to bufferedReflection.
+   * Does NOT create a new generation or update activeObservations.
+   */
+  async doAsyncBufferedReflection(record, _bufferKey, writer) {
+    const freshRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+    const currentRecord = freshRecord ?? record;
+    const observationTokens = currentRecord.observationTokenCount ?? 0;
+    const reflectThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+    const bufferActivation = this.reflectionConfig.bufferActivation ?? 0.5;
+    const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const cycleId = `reflect-buf-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    _ObservationalMemory.reflectionBufferCycleIds.set(_bufferKey, cycleId);
+    const fullObservations = currentRecord.activeObservations ?? "";
+    const allLines = fullObservations.split("\n");
+    const totalLines = allLines.length;
+    const avgTokensPerLine = totalLines > 0 ? observationTokens / totalLines : 0;
+    const activationPointTokens = reflectThreshold * bufferActivation;
+    const linesToReflect = avgTokensPerLine > 0 ? Math.min(Math.floor(activationPointTokens / avgTokensPerLine), totalLines) : totalLines;
+    const activeObservations = allLines.slice(0, linesToReflect).join("\n");
+    const reflectedObservationLineCount = linesToReflect;
+    const sliceTokenEstimate = Math.round(avgTokensPerLine * linesToReflect);
+    const compressionTarget = Math.min(sliceTokenEstimate * bufferActivation, reflectThreshold);
+    omDebug(
+      `[OM:reflect] doAsyncBufferedReflection: slicing observations for reflection \u2014 totalLines=${totalLines}, avgTokPerLine=${avgTokensPerLine.toFixed(1)}, activationPointTokens=${activationPointTokens}, linesToReflect=${linesToReflect}/${totalLines}, sliceTokenEstimate=${sliceTokenEstimate}, compressionTarget=${compressionTarget}`
+    );
+    omDebug(
+      `[OM:reflect] doAsyncBufferedReflection: starting reflector call, recordId=${currentRecord.id}, observationTokens=${sliceTokenEstimate}, compressionTarget=${compressionTarget} (inputTokens), activeObsLength=${activeObservations.length}, reflectedLineCount=${reflectedObservationLineCount}`
+    );
+    if (writer) {
+      const startMarker = this.createBufferingStartMarker({
+        cycleId,
+        operationType: "reflection",
+        tokensToBuffer: sliceTokenEstimate,
+        recordId: record.id,
+        threadId: record.threadId ?? "",
+        threadIds: record.threadId ? [record.threadId] : []
+      });
+      void writer.custom(startMarker).catch(() => {
+      });
+    }
+    const reflectResult = await this.callReflector(
+      activeObservations,
+      void 0,
+      // No manual prompt
+      void 0,
+      // No stream context for background ops
+      compressionTarget,
+      void 0,
+      // No abort signal for background ops
+      true,
+      // Skip continuation hints for async buffering
+      1
+      // Start at compression level 1 for buffered reflection
+    );
+    const reflectionTokenCount = this.tokenCounter.countObservations(reflectResult.observations);
+    omDebug(
+      `[OM:reflect] doAsyncBufferedReflection: reflector returned ${reflectionTokenCount} tokens (${reflectResult.observations?.length} chars), saving to recordId=${currentRecord.id}`
+    );
+    await this.storage.updateBufferedReflection({
+      id: currentRecord.id,
+      reflection: reflectResult.observations,
+      tokenCount: reflectionTokenCount,
+      inputTokenCount: sliceTokenEstimate,
+      reflectedObservationLineCount
+    });
+    omDebug(
+      `[OM:reflect] doAsyncBufferedReflection: bufferedReflection saved with lineCount=${reflectedObservationLineCount}`
+    );
+    if (writer) {
+      const endMarker = this.createBufferingEndMarker({
+        cycleId,
+        operationType: "reflection",
+        startedAt,
+        tokensBuffered: observationTokens,
+        bufferedTokens: reflectionTokenCount,
+        recordId: currentRecord.id,
+        threadId: currentRecord.threadId ?? "",
+        observations: reflectResult.observations
+      });
+      void writer.custom(endMarker).catch(() => {
+      });
+    }
+  }
+  /**
+   * Try to activate buffered reflection when threshold is reached.
+   * Returns true if activation succeeded, false if no buffered content or activation failed.
+   *
+   * @param record - Current OM record
+   * @param lockKey - Lock key for this scope
+   */
+  async tryActivateBufferedReflection(record, lockKey, writer, messageList) {
+    const bufferKey = this.getReflectionBufferKey(lockKey);
+    const asyncOp = _ObservationalMemory.asyncBufferingOps.get(bufferKey);
+    if (asyncOp) {
+      omDebug(`[OM:reflect] tryActivateBufferedReflection: waiting for in-progress op...`);
+      try {
+        await Promise.race([
+          asyncOp,
+          new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout")), 6e4))
+        ]);
+      } catch {
+      }
+    }
+    const freshRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+    omDebug(
+      `[OM:reflect] tryActivateBufferedReflection: recordId=${record.id}, hasBufferedReflection=${!!freshRecord?.bufferedReflection}, bufferedReflectionLen=${freshRecord?.bufferedReflection?.length ?? 0}`
+    );
+    omDebug(
+      `[OM:reflect] tryActivateBufferedReflection: freshRecord.id=${freshRecord?.id}, freshBufferedReflection=${freshRecord?.bufferedReflection ? "present (" + freshRecord.bufferedReflection.length + " chars)" : "empty"}, freshObsTokens=${freshRecord?.observationTokenCount}`
+    );
+    if (!freshRecord?.bufferedReflection) {
+      omDebug(`[OM:reflect] tryActivateBufferedReflection: no buffered reflection after re-fetch, returning false`);
+      return false;
+    }
+    const beforeTokens = freshRecord.observationTokenCount ?? 0;
+    const reflectedLineCount = freshRecord.reflectedObservationLineCount ?? 0;
+    const currentObservations = freshRecord.activeObservations ?? "";
+    const allLines = currentObservations.split("\n");
+    const unreflectedLines = allLines.slice(reflectedLineCount);
+    const unreflectedContent = unreflectedLines.join("\n").trim();
+    const combinedObservations = unreflectedContent ? `${freshRecord.bufferedReflection}
+
+${unreflectedContent}` : freshRecord.bufferedReflection;
+    const combinedTokenCount = this.tokenCounter.countObservations(combinedObservations);
+    omDebug(
+      `[OM:reflect] tryActivateBufferedReflection: activating, beforeTokens=${beforeTokens}, combinedTokenCount=${combinedTokenCount}, reflectedLineCount=${reflectedLineCount}, unreflectedLines=${unreflectedLines.length}`
+    );
+    await this.storage.swapBufferedReflectionToActive({
+      currentRecord: freshRecord,
+      tokenCount: combinedTokenCount
+    });
+    _ObservationalMemory.lastBufferedBoundary.delete(bufferKey);
+    const afterRecord = await this.storage.getObservationalMemory(record.threadId, record.resourceId);
+    const afterTokens = afterRecord?.observationTokenCount ?? 0;
+    omDebug(
+      `[OM:reflect] tryActivateBufferedReflection: activation complete! beforeTokens=${beforeTokens}, afterTokens=${afterTokens}, newRecordId=${afterRecord?.id}, newGenCount=${afterRecord?.generationCount}`
+    );
+    if (writer) {
+      const originalCycleId = _ObservationalMemory.reflectionBufferCycleIds.get(bufferKey);
+      const activationMarker = this.createActivationMarker({
+        cycleId: originalCycleId ?? `reflect-act-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`,
+        operationType: "reflection",
+        chunksActivated: 1,
+        tokensActivated: beforeTokens,
+        observationTokens: afterTokens,
+        messagesActivated: 0,
+        recordId: freshRecord.id,
+        threadId: freshRecord.threadId ?? "",
+        generationCount: afterRecord?.generationCount ?? freshRecord.generationCount ?? 0,
+        observations: afterRecord?.activeObservations
+      });
+      void writer.custom(activationMarker).catch(() => {
+      });
+      await this.persistMarkerToMessage(
+        activationMarker,
+        messageList,
+        freshRecord.threadId ?? "",
+        freshRecord.resourceId ?? void 0
+      );
+    }
+    _ObservationalMemory.reflectionBufferCycleIds.delete(bufferKey);
+    return true;
+  }
   /**
    * Resource-scoped observation: observe ALL threads with unobserved messages.
    * Threads are observed in oldest-first order to ensure no thread's messages
@@ -2754,6 +4254,7 @@ ${result.observations}` : result.observations;
       new Map(threadsToObserve.map((tid) => [tid, messagesByThread.get(tid) ?? []]))
     );
     await this.storage.setObservingFlag(record.id, true);
+    registerOp(record.id, "observing");
     const cycleId = crypto.randomUUID();
     const threadsWithMessages = /* @__PURE__ */ new Map();
     const threadTokensToObserve = /* @__PURE__ */ new Map();
@@ -2969,24 +4470,91 @@ ${result.observations}` : result.observations;
       if (abortSignal?.aborted) {
         throw error;
       }
-      console.error(`[OM] Resource-scoped observation failed:`, error instanceof Error ? error.message : String(error));
+      omError("[OM] Resource-scoped observation failed", error);
     } finally {
       await this.storage.setObservingFlag(record.id, false);
+      unregisterOp(record.id, "observing");
+    }
+  }
+  /**
+   * Check if async reflection should be triggered or activated.
+   * Only handles the async path — will never do synchronous (blocking) reflection.
+   * Safe to call after buffered observation activation.
+   */
+  async maybeAsyncReflect(record, observationTokens, writer, messageList) {
+    if (!this.isAsyncReflectionEnabled()) return;
+    const lockKey = this.getLockKey(record.threadId, record.resourceId);
+    const reflectThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+    omDebug(
+      `[OM:reflect] maybeAsyncReflect: observationTokens=${observationTokens}, reflectThreshold=${reflectThreshold}, isReflecting=${record.isReflecting}, bufferedReflection=${record.bufferedReflection ? "present (" + record.bufferedReflection.length + " chars)" : "empty"}, recordId=${record.id}, genCount=${record.generationCount}`
+    );
+    if (observationTokens < reflectThreshold) {
+      const shouldTrigger = this.shouldTriggerAsyncReflection(observationTokens, lockKey, record);
+      omDebug(`[OM:reflect] below threshold: shouldTrigger=${shouldTrigger}`);
+      if (shouldTrigger) {
+        this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer);
+      }
+      return;
+    }
+    if (record.isReflecting) {
+      if (isOpActiveInProcess(record.id, "reflecting")) {
+        omDebug(`[OM:reflect] skipping - actively reflecting in this process`);
+        return;
+      }
+      omDebug(`[OM:reflect] isReflecting=true but stale (not active in this process), clearing`);
+      await this.storage.setReflectingFlag(record.id, false);
     }
+    omDebug(`[OM:reflect] at/above threshold, trying activation...`);
+    const activationSuccess = await this.tryActivateBufferedReflection(record, lockKey, writer, messageList);
+    omDebug(`[OM:reflect] activationSuccess=${activationSuccess}`);
+    if (activationSuccess) return;
+    omDebug(`[OM:reflect] no buffered reflection, starting background reflection...`);
+    this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer);
   }
   /**
    * Check if reflection needed and trigger if so.
-   * SIMPLIFIED: Always uses synchronous reflection (async buffering disabled).
+   * Supports both synchronous reflection and async buffered reflection.
+   * When async buffering is enabled via `bufferTokens`, reflection is triggered
+   * in the background at intervals, and activated when the threshold is reached.
    */
-  async maybeReflect(record, observationTokens, _threadId, writer, abortSignal) {
+  async maybeReflect(record, observationTokens, _threadId, writer, abortSignal, messageList) {
+    const lockKey = this.getLockKey(record.threadId, record.resourceId);
+    const reflectThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
+    if (this.isAsyncReflectionEnabled() && observationTokens < reflectThreshold) {
+      if (this.shouldTriggerAsyncReflection(observationTokens, lockKey, record)) {
+        this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer);
+      }
+    }
     if (!this.shouldReflect(observationTokens)) {
       return;
     }
     if (record.isReflecting) {
-      return;
+      if (isOpActiveInProcess(record.id, "reflecting")) {
+        omDebug(`[OM:reflect] isReflecting=true and active in this process, skipping`);
+        return;
+      }
+      omDebug(`[OM:reflect] isReflecting=true but NOT active in this process \u2014 stale flag from dead process, clearing`);
+      await this.storage.setReflectingFlag(record.id, false);
+    }
+    if (this.isAsyncReflectionEnabled()) {
+      const activationSuccess = await this.tryActivateBufferedReflection(record, lockKey, writer, messageList);
+      if (activationSuccess) {
+        return;
+      }
+      if (this.reflectionConfig.blockAfter && observationTokens >= this.reflectionConfig.blockAfter) {
+        omDebug(
+          `[OM:reflect] blockAfter exceeded (${observationTokens} >= ${this.reflectionConfig.blockAfter}), falling through to sync reflection`
+        );
+      } else {
+        omDebug(
+          `[OM:reflect] async activation failed, no blockAfter or below it (obsTokens=${observationTokens}, blockAfter=${this.reflectionConfig.blockAfter}) \u2014 starting background reflection`
+        );
+        this.startAsyncBufferedReflection(record, observationTokens, lockKey, writer);
+        return;
+      }
     }
-    const reflectThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
     await this.storage.setReflectingFlag(record.id, true);
+    registerOp(record.id, "reflecting");
     const cycleId = crypto.randomUUID();
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const threadId = _threadId ?? "unknown";
@@ -3072,9 +4640,10 @@ ${result.observations}` : result.observations;
       if (abortSignal?.aborted) {
         throw error;
       }
-      console.error(`[OM] Reflection failed:`, error instanceof Error ? error.message : String(error));
+      omError("[OM] Reflection failed", error);
     } finally {
       await this.storage.setReflectingFlag(record.id, false);
+      unregisterOp(record.id, "reflecting");
     }
   }
   /**
@@ -3122,6 +4691,7 @@ ${result.observations}` : result.observations;
       return;
     }
     await this.storage.setReflectingFlag(record.id, true);
+    registerOp(record.id, "reflecting");
     try {
       const reflectThreshold = this.getMaxThreshold(this.reflectionConfig.observationTokens);
       const reflectResult = await this.callReflector(record.activeObservations, prompt, void 0, reflectThreshold);
@@ -3133,6 +4703,7 @@ ${result.observations}` : result.observations;
       });
     } finally {
       await this.storage.setReflectingFlag(record.id, false);
+      unregisterOp(record.id, "reflecting");
     }
   }
   /**
@@ -3163,6 +4734,7 @@ ${result.observations}` : result.observations;
   async clear(threadId, resourceId) {
     const ids = this.getStorageIds(threadId, resourceId);
     await this.storage.clearObservationalMemory(ids.threadId, ids.resourceId);
+    this.cleanupStaticMaps(ids.threadId ?? ids.resourceId, ids.resourceId);
   }
   /**
    * Get the underlying storage adapter
@@ -3201,5 +4773,5 @@ exports.formatMessagesForObserver = formatMessagesForObserver;
 exports.hasCurrentTaskSection = hasCurrentTaskSection;
 exports.optimizeObservationsForContext = optimizeObservationsForContext;
 exports.parseObserverOutput = parseObserverOutput;
-//# sourceMappingURL=chunk-FQJWVCDF.cjs.map
-//# sourceMappingURL=chunk-FQJWVCDF.cjs.map
+//# sourceMappingURL=chunk-AWE2QQPI.cjs.map
+//# sourceMappingURL=chunk-AWE2QQPI.cjs.map