@martian-engineering/lossless-claw 0.6.2 → 0.7.0

package/src/engine.ts

@@ -43,11 +43,19 @@ import {
   generateExplorationSummary,
   parseFileBlocks,
 } from "./large-files.js";
+import { describeLogError } from "./lcm-log.js";
 import { RetrievalEngine } from "./retrieval.js";
 import { compileSessionPatterns, matchesSessionPattern } from "./session-patterns.js";
 import { logStartupBannerOnce } from "./startup-banner-log.js";
+import {
+  CompactionTelemetryStore,
+  type ConversationCompactionTelemetryRecord,
+  type CacheState,
+  type ActivityBand,
+} from "./store/compaction-telemetry-store.js";
 import {
   ConversationStore,
+  type ConversationRecord,
   type CreateMessagePartInput,
   type MessagePartRecord,
   type MessagePartType,
@@ -62,6 +70,30 @@ type CircuitBreakerState = {
   failures: number;
   openSince: number | null;
 };
+type PromptCacheSnapshot = {
+  lastObservedCacheRead?: number;
+  lastObservedCacheWrite?: number;
+  cacheState: CacheState;
+  retention?: string;
+  sawExplicitBreak: boolean;
+};
+type IncrementalCompactionDecision = {
+  shouldCompact: boolean;
+  cacheState: CacheState;
+  maxPasses: number;
+  rawTokensOutsideTail: number;
+  threshold: number;
+  leafChunkTokens: number;
+  fallbackLeafChunkTokens: number[];
+  activityBand: ActivityBand;
+  allowCondensedPasses: boolean;
+};
+type DynamicLeafChunkBounds = {
+  floor: number;
+  medium: number;
+  high: number;
+  max: number;
+};
 type TranscriptRewriteReplacement = {
   entryId: string;
   message: AgentMessage;
@@ -82,6 +114,13 @@ type ContextEngineMaintenanceRuntimeContext = Record<string, unknown> & {
 };
 
 const TRANSCRIPT_GC_BATCH_SIZE = 12;
+const HOT_CACHE_HYSTERESIS_TURNS = 2;
+const DYNAMIC_LEAF_CHUNK_MEDIUM_MULTIPLIER = 1.5;
+const DYNAMIC_LEAF_CHUNK_HIGH_MULTIPLIER = 2;
+const DYNAMIC_ACTIVITY_MEDIUM_UPSHIFT_FACTOR = 0.5;
+const DYNAMIC_ACTIVITY_MEDIUM_DOWNSHIFT_FACTOR = 0.35;
+const DYNAMIC_ACTIVITY_HIGH_UPSHIFT_FACTOR = 1.0;
+const DYNAMIC_ACTIVITY_HIGH_DOWNSHIFT_FACTOR = 0.75;
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -834,12 +873,25 @@ function isBootstrapMessage(value: unknown): value is AgentMessage {
   return "content" in msg || ("command" in msg && "output" in msg);
 }
 
+function extractCanonicalBootstrapMessage(value: unknown): AgentMessage | null {
+  if (isBootstrapMessage(value)) {
+    return value;
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const entry = value as { type?: unknown; message?: unknown };
+  if ("message" in entry) {
+    if (entry.type !== undefined && entry.type !== "message") {
+      return null;
+    }
+    return isBootstrapMessage(entry.message) ? entry.message : null;
+  }
+  return null;
+}
+
 function extractBootstrapMessageCandidate(value: unknown): AgentMessage | null {
-  const candidate =
-    value && typeof value === "object" && "message" in value
-      ? (value as { message?: unknown }).message
-      : value;
-  return isBootstrapMessage(candidate) ? candidate : null;
+  return extractCanonicalBootstrapMessage(value);
 }
 
 function parseBootstrapJsonl(raw: string, options?: {
@@ -862,9 +914,6 @@ function parseBootstrapJsonl(raw: string, options?: {
         messages.push(candidate);
         continue;
       }
-      if (options?.strict) {
-        hadMalformedLine = true;
-      }
     } catch {
       if (options?.strict) {
         hadMalformedLine = true;
@@ -1017,7 +1066,12 @@ function readFileSegment(sessionFile: string, offset: number): string | null {
   }
 }
 
-function readLastJsonlEntryBeforeOffset(sessionFile: string, offset: number): string | null {
+function readLastJsonlEntryBeforeOffset(
+  sessionFile: string,
+  offset: number,
+  messageOnly = false,
+  matcher?: (message: AgentMessage) => boolean,
+): string | null {
   const chunkSize = 16_384;
   let fd: number | null = null;
   try {
@@ -1029,16 +1083,23 @@ function readLastJsonlEntryBeforeOffset(sessionFile: string, offset: number): st
     fd = openSync(sessionFile, "r");
     let cursor = safeOffset;
     let carry = "";
-    while (cursor > 0) {
-      const start = Math.max(0, cursor - chunkSize);
-      const length = cursor - start;
-      const buffer = Buffer.alloc(length);
-      readSync(fd, buffer, 0, length, start);
-      carry = buffer.toString("utf8") + carry;
+    let reachedStart = false;
+    while (cursor > 0 || (reachedStart && carry.length > 0)) {
+      if (!reachedStart) {
+        const start = Math.max(0, cursor - chunkSize);
+        const length = cursor - start;
+        const buffer = Buffer.alloc(length);
+        readSync(fd, buffer, 0, length, start);
+        carry = buffer.toString("utf8") + carry;
+        cursor = start;
+        if (start === 0) {
+          reachedStart = true;
+        }
+      }
 
       const trimmedEnd = carry.replace(/\s+$/u, "");
       if (!trimmedEnd) {
-        cursor = start;
+        if (reachedStart) break;
         carry = "";
         continue;
       }
@@ -1047,17 +1108,36 @@ function readLastJsonlEntryBeforeOffset(sessionFile: string, offset: number): st
       if (newlineIndex >= 0) {
         const candidate = trimmedEnd.slice(newlineIndex + 1).trim();
         if (candidate) {
+          if (messageOnly) {
+            let matchedMessage: AgentMessage | null = null;
+            try {
+              matchedMessage = extractBootstrapMessageCandidate(JSON.parse(candidate));
+            } catch { /* not valid JSON, skip */ }
+            if (!matchedMessage || (matcher && !matcher(matchedMessage))) {
+              carry = trimmedEnd.slice(0, newlineIndex);
+              continue;
+            }
+          }
           return candidate;
         }
         carry = trimmedEnd.slice(0, newlineIndex);
-        cursor = start;
         continue;
       }
 
-      if (start === 0) {
-        return trimmedEnd.trim() || null;
+      // No newline found — entire trimmedEnd is one line
+      if (reachedStart) {
+        const firstLine = trimmedEnd.trim() || null;
+        if (firstLine && messageOnly) {
+          let matchedMessage: AgentMessage | null = null;
+          try {
+            matchedMessage = extractBootstrapMessageCandidate(JSON.parse(firstLine));
+          } catch { /* not valid JSON */ }
+          if (!matchedMessage || (matcher && !matcher(matchedMessage))) return null;
+        }
+        return firstLine;
       }
-      cursor = start;
+      // Need more data from earlier in the file
+      continue;
     }
     return null;
   } catch {
@@ -1128,6 +1208,7 @@ export class LcmContextEngine implements ContextEngine {
 
   private conversationStore: ConversationStore;
   private summaryStore: SummaryStore;
+  private compactionTelemetryStore: CompactionTelemetryStore;
   private assembler: ContextAssembler;
   private compaction: CompactionEngine;
   private retrieval: RetrievalEngine;
@@ -1197,6 +1278,7 @@ export class LcmContextEngine implements ContextEngine {
       fts5Available: this.fts5Available,
     });
     this.summaryStore = new SummaryStore(this.db, { fts5Available: this.fts5Available });
+    this.compactionTelemetryStore = new CompactionTelemetryStore(this.db);
 
     if (!this.fts5Available) {
       this.deps.log.warn(
@@ -1242,6 +1324,7 @@ export class LcmContextEngine implements ContextEngine {
       this.conversationStore,
       this.summaryStore,
       compactionConfig,
+      this.deps.log,
     );
 
     this.retrieval = new RetrievalEngine(this.conversationStore, this.summaryStore);
@@ -1308,10 +1391,17 @@ export class LcmContextEngine implements ContextEngine {
   private recordCompactionAuthFailure(key: string): void {
     const state = this.getCircuitBreakerState(key);
     state.failures++;
+    const halfThreshold = Math.ceil(this.config.circuitBreakerThreshold / 2);
+    if (state.failures === halfThreshold && state.failures < this.config.circuitBreakerThreshold) {
+      this.deps.log.warn(
+        `[lcm] WARNING: compaction degraded — ${state.failures}/${this.config.circuitBreakerThreshold} consecutive auth failures for ${key}`,
+      );
+    }
     if (state.failures >= this.config.circuitBreakerThreshold) {
       state.openSince = Date.now();
-      console.error(
-        `[lcm] compaction circuit breaker OPEN: ${state.failures} consecutive auth failures for ${key}. Compaction halted. Will auto-retry after ${Math.round(this.config.circuitBreakerCooldownMs / 60000)}m or gateway restart.`,
+      const cooldownMin = Math.round(this.config.circuitBreakerCooldownMs / 60000);
+      this.deps.log.warn(
+        `[lcm] CIRCUIT BREAKER OPEN: compaction disabled for ${key}. Auto-retry in ${cooldownMin}m. LCM is operating in degraded mode.`,
       );
     }
   }
@@ -1322,7 +1412,7 @@ export class LcmContextEngine implements ContextEngine {
       return;
     }
     if (state.failures > 0 || state.openSince !== null) {
-      console.error(
+      this.deps.log.info(
         `[lcm] compaction circuit breaker CLOSED: successful compaction for ${key} after ${state.failures} prior failures.`,
       );
     }
@@ -1419,6 +1509,486 @@ export class LcmContextEngine implements ContextEngine {
     return cap != null && cap > 0 ? Math.min(budget, cap) : budget;
   }
 
+  /** Normalize token counters that may legitimately be zero. */
+  private normalizeOptionalCount(value: unknown): number | undefined {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      return undefined;
+    }
+    return Math.floor(value);
+  }
+
+  /** Treat a recent cache hit as still-hot for a couple of turns unless telemetry observed a later break. */
+  private shouldApplyHotCacheHysteresis(
+    telemetry: ConversationCompactionTelemetryRecord | null,
+  ): boolean {
+    if (!telemetry?.lastObservedCacheHitAt) {
+      return false;
+    }
+    if (
+      telemetry.lastObservedCacheBreakAt
+      && telemetry.lastObservedCacheBreakAt >= telemetry.lastObservedCacheHitAt
+    ) {
+      return false;
+    }
+    return telemetry.turnsSinceLeafCompaction <= HOT_CACHE_HYSTERESIS_TURNS;
+  }
+
+  /** Resolve the effective cache state the incremental compaction policy should react to. */
+  private resolveCacheAwareState(
+    telemetry: ConversationCompactionTelemetryRecord | null,
+  ): CacheState {
+    if (!telemetry) {
+      return "unknown";
+    }
+    if (telemetry.cacheState === "hot") {
+      return "hot";
+    }
+    if (this.shouldApplyHotCacheHysteresis(telemetry)) {
+      return "hot";
+    }
+    return telemetry.cacheState;
+  }
+
+  /** Decide whether a hot cache still has enough real token-budget headroom to skip incremental maintenance. */
+  private isComfortablyUnderTokenBudget(params: {
+    currentTokenCount?: number;
+    tokenBudget: number;
+  }): boolean {
+    if (
+      typeof params.currentTokenCount !== "number"
+      || !Number.isFinite(params.currentTokenCount)
+      || params.currentTokenCount < 0
+    ) {
+      return false;
+    }
+    const budget = Math.max(1, Math.floor(params.tokenBudget));
+    const safeBudget = Math.floor(
+      budget * (1 - this.config.cacheAwareCompaction.hotCacheBudgetHeadroomRatio),
+    );
+    return params.currentTokenCount <= safeBudget;
+  }
+
+  /** Resolve bounded dynamic leaf chunk sizes from config and the active token budget. */
+  private resolveDynamicLeafChunkBounds(tokenBudget?: number): DynamicLeafChunkBounds {
+    const floor = Math.max(1, Math.floor(this.config.leafChunkTokens));
+    const configuredMax = this.config.dynamicLeafChunkTokens.enabled
+      ? Math.max(floor, Math.floor(this.config.dynamicLeafChunkTokens.max))
+      : floor;
+    const budgetCap =
+      typeof tokenBudget === "number" &&
+      Number.isFinite(tokenBudget) &&
+      tokenBudget > 0
+        ? Math.max(floor, Math.floor(tokenBudget * this.config.contextThreshold))
+        : configuredMax;
+    const max = Math.max(floor, Math.min(configuredMax, budgetCap));
+    const medium = Math.max(
+      floor,
+      Math.min(max, Math.floor(floor * DYNAMIC_LEAF_CHUNK_MEDIUM_MULTIPLIER)),
+    );
+    const high = Math.max(
+      floor,
+      Math.min(max, Math.floor(floor * DYNAMIC_LEAF_CHUNK_HIGH_MULTIPLIER)),
+    );
+    return { floor, medium, high, max };
+  }
+
+  /** Classify the current refill rate into a simple step band with downshift hysteresis. */
+  private classifyDynamicLeafActivityBand(params: {
+    lastActivityBand?: ActivityBand;
+    tokensAccumulatedSinceLeafCompaction: number;
+    turnsSinceLeafCompaction: number;
+    floor: number;
+  }): ActivityBand {
+    const turns = Math.max(1, params.turnsSinceLeafCompaction);
+    const tokensPerTurn = params.tokensAccumulatedSinceLeafCompaction / turns;
+    const mediumUpshift = params.floor * DYNAMIC_ACTIVITY_MEDIUM_UPSHIFT_FACTOR;
+    const mediumDownshift = params.floor * DYNAMIC_ACTIVITY_MEDIUM_DOWNSHIFT_FACTOR;
+    const highUpshift = params.floor * DYNAMIC_ACTIVITY_HIGH_UPSHIFT_FACTOR;
+    const highDownshift = params.floor * DYNAMIC_ACTIVITY_HIGH_DOWNSHIFT_FACTOR;
+    const lastBand = params.lastActivityBand ?? "low";
+
+    if (lastBand === "high") {
+      if (tokensPerTurn >= highDownshift) {
+        return "high";
+      }
+      return tokensPerTurn >= mediumDownshift ? "medium" : "low";
+    }
+    if (lastBand === "medium") {
+      if (tokensPerTurn >= highUpshift) {
+        return "high";
+      }
+      if (tokensPerTurn < mediumDownshift) {
+        return "low";
+      }
+      return "medium";
+    }
+    if (tokensPerTurn >= highUpshift) {
+      return "high";
+    }
+    if (tokensPerTurn >= mediumUpshift) {
+      return "medium";
+    }
+    return "low";
+  }
+
+  /** Map an activity band to the corresponding working leaf chunk size. */
+  private resolveLeafChunkTokensForBand(
+    band: ActivityBand,
+    bounds: DynamicLeafChunkBounds,
+  ): number {
+    switch (band) {
+      case "high":
+        return bounds.high;
+      case "medium":
+        return bounds.medium;
+      default:
+        return bounds.floor;
+    }
+  }
+
+  /** Build descending fallback chunk sizes used when a provider rejects a larger chunk. */
+  private buildLeafChunkFallbacks(params: {
+    preferred: number;
+    bounds: DynamicLeafChunkBounds;
+  }): number[] {
+    const ordered = [params.preferred, params.bounds.max, params.bounds.high, params.bounds.medium, params.bounds.floor];
+    const seen = new Set<number>();
+    const fallbacks: number[] = [];
+    for (const value of ordered) {
+      const normalized = Math.max(params.bounds.floor, Math.floor(value));
+      if (seen.has(normalized)) {
+        continue;
+      }
+      seen.add(normalized);
+      fallbacks.push(normalized);
+    }
+    return fallbacks.sort((a, b) => b - a);
+  }
+
+  /** Detect provider/model token-limit failures that should trigger a lower chunk retry. */
+  private isRecoverableLeafChunkOverflowError(error: unknown): boolean {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    if (!message) {
+      return false;
+    }
+    return [
+      "context length",
+      "context window",
+      "maximum context",
+      "max context",
+      "too many tokens",
+      "too many input tokens",
+      "input tokens",
+      "token limit",
+      "context limit",
+      "input is too large",
+      "input too large",
+      "prompt is too long",
+      "request too large",
+      "exceeds the model",
+      "exceeds context",
+    ].some((fragment) => message.includes(fragment));
+  }
+
+  /** Extract the current prompt-cache snapshot from runtime context, if present. */
+  private readPromptCacheSnapshot(runtimeContext?: Record<string, unknown>): PromptCacheSnapshot | null {
+    const promptCache = asRecord(runtimeContext?.promptCache);
+    if (!promptCache) {
+      return null;
+    }
+
+    const lastCallUsage = asRecord(promptCache.lastCallUsage);
+    const observation = asRecord(promptCache.observation);
+    const cacheRead = this.normalizeOptionalCount(lastCallUsage?.cacheRead);
+    const cacheWrite = this.normalizeOptionalCount(lastCallUsage?.cacheWrite);
+    const sawExplicitBreak = safeBoolean(observation?.broke) === true;
+    const retention = safeString(promptCache.retention)?.trim();
+    const hasUsageSignal = cacheRead !== undefined || cacheWrite !== undefined;
+    const hasObservationSignal =
+      typeof observation?.cacheRead === "number"
+      || typeof observation?.previousCacheRead === "number"
+      || sawExplicitBreak;
+
+    let cacheState: CacheState = "unknown";
+    if (sawExplicitBreak) {
+      cacheState = "cold";
+    } else if (typeof cacheRead === "number" && cacheRead > 0) {
+      cacheState = "hot";
+    } else if (hasUsageSignal || hasObservationSignal) {
+      cacheState = "cold";
+    }
+
+    return {
+      ...(cacheRead !== undefined ? { lastObservedCacheRead: cacheRead } : {}),
+      ...(cacheWrite !== undefined ? { lastObservedCacheWrite: cacheWrite } : {}),
+      cacheState,
+      ...(retention ? { retention } : {}),
+      sawExplicitBreak,
+    };
+  }
+
+  /** Persist the current turn's compaction telemetry for later policy decisions. */
+  private async updateCompactionTelemetry(params: {
+    conversationId: number;
+    runtimeContext?: Record<string, unknown>;
+    tokenBudget?: number;
+    rawTokensOutsideTail?: number;
+  }): Promise<ConversationCompactionTelemetryRecord | null> {
+    const snapshot = this.readPromptCacheSnapshot(params.runtimeContext);
+    const existing = await this.compactionTelemetryStore.getConversationCompactionTelemetry(
+      params.conversationId,
+    );
+    if (!snapshot && params.rawTokensOutsideTail === undefined) {
+      return existing;
+    }
+
+    const now = new Date();
+    const bounds = this.resolveDynamicLeafChunkBounds(params.tokenBudget);
+    const turnsSinceLeafCompaction =
+      (existing?.turnsSinceLeafCompaction ?? 0) + 1;
+    const tokensAccumulatedSinceLeafCompaction =
+      params.rawTokensOutsideTail ?? existing?.tokensAccumulatedSinceLeafCompaction ?? 0;
+    const lastActivityBand = this.classifyDynamicLeafActivityBand({
+      lastActivityBand: existing?.lastActivityBand,
+      tokensAccumulatedSinceLeafCompaction,
+      turnsSinceLeafCompaction,
+      floor: bounds.floor,
+    });
+    await this.compactionTelemetryStore.upsertConversationCompactionTelemetry({
+      conversationId: params.conversationId,
+      lastObservedCacheRead: snapshot?.lastObservedCacheRead ?? existing?.lastObservedCacheRead ?? null,
+      lastObservedCacheWrite:
+        snapshot?.lastObservedCacheWrite ?? existing?.lastObservedCacheWrite ?? null,
+      lastObservedCacheHitAt:
+        snapshot?.cacheState === "hot"
+          ? now
+          : existing?.lastObservedCacheHitAt ?? null,
+      lastObservedCacheBreakAt:
+        snapshot?.sawExplicitBreak
+          ? now
+          : existing?.lastObservedCacheBreakAt ?? null,
+      cacheState: snapshot?.cacheState ?? existing?.cacheState ?? "unknown",
+      retention: snapshot?.retention ?? existing?.retention ?? null,
+      lastLeafCompactionAt: existing?.lastLeafCompactionAt ?? null,
+      turnsSinceLeafCompaction,
+      tokensAccumulatedSinceLeafCompaction,
+      lastActivityBand,
+    });
+    const updated = await this.compactionTelemetryStore.getConversationCompactionTelemetry(
+      params.conversationId,
+    );
+    if (updated) {
+      this.deps.log.debug(
+        `[lcm] compaction telemetry updated: conversation=${params.conversationId} cacheState=${updated.cacheState} cacheRead=${updated.lastObservedCacheRead ?? "null"} cacheWrite=${updated.lastObservedCacheWrite ?? "null"} retention=${updated.retention ?? "null"} turnsSinceLeafCompaction=${updated.turnsSinceLeafCompaction} tokensSinceLeafCompaction=${updated.tokensAccumulatedSinceLeafCompaction} activityBand=${updated.lastActivityBand} rawTokensOutsideTail=${params.rawTokensOutsideTail ?? "null"} tokenBudget=${params.tokenBudget ?? "null"}`,
+      );
+    }
+    return updated;
+  }
+
+  /** Reset refill counters after any successful leaf-producing compaction. */
+  private async markLeafCompactionTelemetrySuccess(params: {
+    conversationId: number;
+    activityBand?: ActivityBand;
+  }): Promise<void> {
+    const existing = await this.compactionTelemetryStore.getConversationCompactionTelemetry(
+      params.conversationId,
+    );
+    await this.compactionTelemetryStore.upsertConversationCompactionTelemetry({
+      conversationId: params.conversationId,
+      lastObservedCacheRead: existing?.lastObservedCacheRead ?? null,
+      lastObservedCacheWrite: existing?.lastObservedCacheWrite ?? null,
+      lastObservedCacheHitAt: existing?.lastObservedCacheHitAt ?? null,
+      lastObservedCacheBreakAt: existing?.lastObservedCacheBreakAt ?? null,
+      cacheState: existing?.cacheState ?? "unknown",
+      retention: existing?.retention ?? null,
+      lastLeafCompactionAt: new Date(),
+      turnsSinceLeafCompaction: 0,
+      tokensAccumulatedSinceLeafCompaction: 0,
+      lastActivityBand: params.activityBand ?? existing?.lastActivityBand ?? "low",
+    });
+    this.deps.log.debug(
+      `[lcm] compaction telemetry reset after leaf compaction: conversation=${params.conversationId} cacheState=${existing?.cacheState ?? "unknown"} activityBand=${params.activityBand ?? existing?.lastActivityBand ?? "low"}`,
+    );
+  }
+
+  /** Emit an operational trace for the incremental compaction policy decision. */
+  private logIncrementalCompactionDecision(params: {
+    conversationId: number;
+    cacheState: CacheState;
+    activityBand: ActivityBand;
+    triggerLeafChunkTokens: number;
+    preferredLeafChunkTokens: number;
+    fallbackLeafChunkTokens: number[];
+    rawTokensOutsideTail: number;
+    threshold: number;
+    shouldCompact: boolean;
+    maxPasses: number;
+    allowCondensedPasses: boolean;
+    reason: string;
+  }): IncrementalCompactionDecision {
+    this.deps.log.info(
+      `[lcm] incremental compaction decision: conversation=${params.conversationId} cacheState=${params.cacheState} activityBand=${params.activityBand} triggerLeafChunkTokens=${params.triggerLeafChunkTokens} preferredLeafChunkTokens=${params.preferredLeafChunkTokens} fallbackLeafChunkTokens=${params.fallbackLeafChunkTokens.join(",")} rawTokensOutsideTail=${params.rawTokensOutsideTail} threshold=${params.threshold} shouldCompact=${params.shouldCompact} maxPasses=${params.maxPasses} allowCondensedPasses=${params.allowCondensedPasses} reason=${params.reason}`,
+    );
+    return {
+      shouldCompact: params.shouldCompact,
+      cacheState: params.cacheState,
+      maxPasses: params.maxPasses,
+      rawTokensOutsideTail: params.rawTokensOutsideTail,
+      threshold: params.threshold,
+      leafChunkTokens: params.preferredLeafChunkTokens,
+      fallbackLeafChunkTokens: params.fallbackLeafChunkTokens,
+      activityBand: params.activityBand,
+      allowCondensedPasses: params.allowCondensedPasses,
+    };
+  }
+
+  /** Resolve the cache-aware incremental-compaction policy for the current session. */
+  private async evaluateIncrementalCompaction(params: {
+    conversationId: number;
+    tokenBudget: number;
+    currentTokenCount?: number;
+  }): Promise<IncrementalCompactionDecision> {
+    const telemetry = await this.compactionTelemetryStore.getConversationCompactionTelemetry(
+      params.conversationId,
+    );
+    const cacheState =
+      this.config.cacheAwareCompaction.enabled
+        ? this.resolveCacheAwareState(telemetry)
+        : "unknown";
+    const bounds = this.resolveDynamicLeafChunkBounds(params.tokenBudget);
+    const activityBand =
+      this.config.dynamicLeafChunkTokens.enabled
+        ? this.classifyDynamicLeafActivityBand({
+          lastActivityBand: telemetry?.lastActivityBand,
+          tokensAccumulatedSinceLeafCompaction:
+            telemetry?.tokensAccumulatedSinceLeafCompaction ?? 0,
+          turnsSinceLeafCompaction: telemetry?.turnsSinceLeafCompaction ?? 0,
+          floor: bounds.floor,
+        })
+        : "low";
+    const triggerLeafChunkTokens =
+      this.config.dynamicLeafChunkTokens.enabled && cacheState === "hot"
+        ? bounds.max
+        : this.config.dynamicLeafChunkTokens.enabled
+          ? this.resolveLeafChunkTokensForBand(activityBand, bounds)
+          : bounds.floor;
+    const preferredLeafChunkTokens =
+      this.config.cacheAwareCompaction.enabled && (cacheState === "cold" || cacheState === "hot")
+        ? bounds.max
+        : triggerLeafChunkTokens;
+    const fallbackLeafChunkTokens = this.buildLeafChunkFallbacks({
+      preferred: preferredLeafChunkTokens,
+      bounds,
+    });
+    const leafTrigger = await this.compaction.evaluateLeafTrigger(
+      params.conversationId,
+      triggerLeafChunkTokens,
+    );
+    if (!leafTrigger.shouldCompact) {
+      return this.logIncrementalCompactionDecision({
+        conversationId: params.conversationId,
+        cacheState,
+        activityBand,
+        triggerLeafChunkTokens,
+        preferredLeafChunkTokens,
+        fallbackLeafChunkTokens,
+        rawTokensOutsideTail: leafTrigger.rawTokensOutsideTail,
+        threshold: leafTrigger.threshold,
+        shouldCompact: false,
+        maxPasses: 1,
+        allowCondensedPasses: false,
+        reason: "below-leaf-trigger",
+      });
+    }
+
+    const budgetDecision = await this.compaction.evaluate(
+      params.conversationId,
+      params.tokenBudget,
+      params.currentTokenCount,
+    );
+    if (budgetDecision.shouldCompact) {
+      return this.logIncrementalCompactionDecision({
+        conversationId: params.conversationId,
+        cacheState,
+        activityBand,
+        triggerLeafChunkTokens,
+        preferredLeafChunkTokens,
+        fallbackLeafChunkTokens,
+        rawTokensOutsideTail: leafTrigger.rawTokensOutsideTail,
+        threshold: leafTrigger.threshold,
+        shouldCompact: true,
+        maxPasses: 1,
+        allowCondensedPasses: true,
+        reason: "budget-trigger",
+      });
+    }
+
+    if (
+      cacheState === "hot"
+      && this.isComfortablyUnderTokenBudget({
+        currentTokenCount: params.currentTokenCount,
+        tokenBudget: params.tokenBudget,
+      })
+    ) {
+      return this.logIncrementalCompactionDecision({
+        conversationId: params.conversationId,
+        cacheState,
+        activityBand,
+        triggerLeafChunkTokens,
+        preferredLeafChunkTokens,
+        fallbackLeafChunkTokens,
+        rawTokensOutsideTail: leafTrigger.rawTokensOutsideTail,
+        threshold: leafTrigger.threshold,
+        shouldCompact: false,
+        maxPasses: 1,
+        allowCondensedPasses: false,
+        reason: "hot-cache-budget-headroom",
+      });
+    }
+
+    if (
+      cacheState === "hot"
+      && leafTrigger.rawTokensOutsideTail
+        < Math.floor(
+          leafTrigger.threshold * this.config.cacheAwareCompaction.hotCachePressureFactor,
+        )
+    ) {
+      return this.logIncrementalCompactionDecision({
+        conversationId: params.conversationId,
+        cacheState,
+        activityBand,
+        triggerLeafChunkTokens,
+        preferredLeafChunkTokens,
+        fallbackLeafChunkTokens,
+        rawTokensOutsideTail: leafTrigger.rawTokensOutsideTail,
+        threshold: leafTrigger.threshold,
+        shouldCompact: false,
+        maxPasses: 1,
+        allowCondensedPasses: false,
+        reason: "hot-cache-defer",
+      });
+    }
+
+    const maxPasses =
+      cacheState === "cold"
+        ? Math.max(1, this.config.cacheAwareCompaction.maxColdCacheCatchupPasses)
+        : 1;
+    return this.logIncrementalCompactionDecision({
+      conversationId: params.conversationId,
+      cacheState,
+      activityBand,
+      triggerLeafChunkTokens,
+      preferredLeafChunkTokens,
+      fallbackLeafChunkTokens,
+      rawTokensOutsideTail: leafTrigger.rawTokensOutsideTail,
+      threshold: leafTrigger.threshold,
+      shouldCompact: true,
+      maxPasses,
+      allowCondensedPasses: cacheState !== "hot",
+      reason: cacheState === "cold" ? "cold-cache-catchup" : "leaf-trigger",
+    });
+  }
+
   /** Resolve an LCM conversation id from a session key via the session store. */
   private async resolveConversationIdForSessionKey(
     sessionKey: string,
@@ -1448,6 +2018,23 @@ export class LcmContextEngine implements ContextEngine {
     }
   }
 
+  /** Format stable session identifiers for LCM diagnostic logs. */
+  private formatSessionLogContext(params: {
+    conversationId: number;
+    sessionId: string;
+    sessionKey?: string;
+  }): string {
+    const parts = [
+      `conversation=${params.conversationId}`,
+      `session=${params.sessionId}`,
+    ];
+    const trimmedSessionKey = params.sessionKey?.trim();
+    if (trimmedSessionKey) {
+      parts.push(`sessionKey=${trimmedSessionKey}`);
+    }
+    return parts.join(" ");
+  }
+
   /** Build a summarize callback with runtime provider fallback handling. */
   private async resolveSummarize(params: {
     legacyParams?: Record<string, unknown>;
@@ -1483,11 +2070,13 @@ export class LcmContextEngine implements ContextEngine {
           breakerKey: runtimeSummarizer.breakerKey,
         };
       }
-      console.error(`[lcm] resolveSummarize: createLcmSummarizeFromLegacyParams returned undefined`);
+      this.deps.log.error(`[lcm] resolveSummarize: createLcmSummarizeFromLegacyParams returned undefined`);
     } catch (err) {
-      console.error(`[lcm] resolveSummarize failed, using emergency fallback:`, err instanceof Error ? err.message : err);
+      this.deps.log.error(
+        `[lcm] resolveSummarize failed, using emergency fallback: ${describeLogError(err)}`,
+      );
     }
-    console.error(`[lcm] resolveSummarize: FALLING BACK TO EMERGENCY TRUNCATION`);
+    this.deps.log.error(`[lcm] resolveSummarize: FALLING BACK TO EMERGENCY TRUNCATION`);
     return { summarize: createEmergencyFallbackSummarize(), summaryModel: "unknown" };
   }
 
@@ -1826,17 +2415,18 @@ export class LcmContextEngine implements ContextEngine {
     conversationId: number;
     historicalMessages: AgentMessage[];
   }): Promise<{
+    blockedByImportCap: boolean;
     importedMessages: number;
     hasOverlap: boolean;
   }> {
     const { sessionId, conversationId, historicalMessages } = params;
     if (historicalMessages.length === 0) {
-      return { importedMessages: 0, hasOverlap: false };
+      return { blockedByImportCap: false, importedMessages: 0, hasOverlap: false };
     }
 
     const latestDbMessage = await this.conversationStore.getLastMessage(conversationId);
     if (!latestDbMessage) {
-      return { importedMessages: 0, hasOverlap: false };
+      return { blockedByImportCap: false, importedMessages: 0, hasOverlap: false };
     }
 
     const storedHistoricalMessages = historicalMessages.map((message) => toStoredMessage(message));
@@ -1857,7 +2447,7 @@ export class LcmContextEngine implements ContextEngine {
         }
       }
       if (dbOccurrences === historicalOccurrences) {
-        return { importedMessages: 0, hasOverlap: true };
+        return { blockedByImportCap: false, importedMessages: 0, hasOverlap: true };
       }
     }
 
@@ -1909,13 +2499,27 @@ export class LcmContextEngine implements ContextEngine {
     }
 
     if (anchorIndex < 0) {
-      return { importedMessages: 0, hasOverlap: false };
+      return { blockedByImportCap: false, importedMessages: 0, hasOverlap: false };
     }
     if (anchorIndex >= historicalMessages.length - 1) {
-      return { importedMessages: 0, hasOverlap: true };
+      return { blockedByImportCap: false, importedMessages: 0, hasOverlap: true };
     }
 
     const missingTail = historicalMessages.slice(anchorIndex + 1);
+
+    const existingDbCount = await this.conversationStore.getMessageCount(conversationId);
+    if (existingDbCount > 0 && missingTail.length > Math.max(existingDbCount * 0.2, 50)) {
+      const sessionContext = this.formatSessionLogContext({
+        conversationId,
+        sessionId,
+        sessionKey: params.sessionKey,
+      });
+      this.deps.log.warn(
+        `[lcm] reconcileSessionTail: import cap exceeded for ${sessionContext} — would import ${missingTail.length} messages (existing: ${existingDbCount}). Aborting to prevent flood.`,
+      );
+      return { blockedByImportCap: true, importedMessages: 0, hasOverlap: true };
+    }
+
     let importedMessages = 0;
     for (const message of missingTail) {
       const result = await this.ingestSingle({ sessionId, sessionKey: params.sessionKey, message });
@@ -1924,7 +2528,38 @@ export class LcmContextEngine implements ContextEngine {
       }
     }
 
-    return { importedMessages, hasOverlap: true };
+    return { blockedByImportCap: false, importedMessages, hasOverlap: true };
+  }
+
+  /**
+   * Persist bootstrap checkpoint metadata anchored to the current DB frontier.
+   *
+   * We intentionally checkpoint the session file's current EOF while hashing the
+   * latest persisted DB message. This keeps append-only recovery aligned with the
+   * canonical LCM frontier even when trailing transcript entries are pruned or
+   * otherwise noncanonical.
+   */
+  private async refreshBootstrapState(params: {
+    conversationId: number;
+    sessionFile: string;
+    fileStats?: { size: number; mtimeMs: number };
+  }): Promise<void> {
+    const latestDbMessage = await this.conversationStore.getLastMessage(params.conversationId);
+    const fileStats = params.fileStats ?? statSync(params.sessionFile);
+    await this.summaryStore.upsertConversationBootstrapState({
+      conversationId: params.conversationId,
+      sessionFilePath: params.sessionFile,
+      lastSeenSize: fileStats.size,
+      lastSeenMtimeMs: Math.trunc(fileStats.mtimeMs),
+      lastProcessedOffset: fileStats.size,
+      lastProcessedEntryHash: latestDbMessage
+        ? createBootstrapEntryHash({
+            role: latestDbMessage.role,
+            content: latestDbMessage.content,
+            tokenCount: latestDbMessage.tokenCount,
+          })
+        : null,
+    });
   }
 
   async bootstrap(params: {
@@ -1957,19 +2592,14 @@ export class LcmContextEngine implements ContextEngine {
         this.conversationStore.withTransaction(async () => {
           const persistBootstrapState = async (
             conversationId: number,
-            historicalMessages: AgentMessage[],
           ): Promise<void> => {
-            const lastMessage =
-              historicalMessages.length > 0
-                ? toStoredMessage(historicalMessages[historicalMessages.length - 1]!)
-                : null;
-            await this.summaryStore.upsertConversationBootstrapState({
+            await this.refreshBootstrapState({
               conversationId,
-              sessionFilePath: params.sessionFile,
-              lastSeenSize: sessionFileSize,
-              lastSeenMtimeMs: sessionFileMtimeMs,
-              lastProcessedOffset: sessionFileSize,
-              lastProcessedEntryHash: createBootstrapEntryHash(lastMessage),
+              sessionFile: params.sessionFile,
+              fileStats: {
+                size: sessionFileSize,
+                mtimeMs: sessionFileMtimeMs,
+              },
             });
           };
 
@@ -2019,6 +2649,8 @@ export class LcmContextEngine implements ContextEngine {
             const tailEntryRaw = readLastJsonlEntryBeforeOffset(
               params.sessionFile,
               bootstrapState.lastProcessedOffset,
+              true,
+              (message) => createBootstrapEntryHash(toStoredMessage(message)) === latestDbHash,
             );
             const tailEntryMessage = readBootstrapMessageFromJsonLine(tailEntryRaw);
             const tailEntryHash = tailEntryMessage
@@ -2052,14 +2684,7 @@ export class LcmContextEngine implements ContextEngine {
                   }
                 }
 
-                const lastAppendedMessage =
-                  appended.messages.length > 0
-                    ? appended.messages[appended.messages.length - 1]!
-                    : tailEntryMessage;
-                await persistBootstrapState(
-                  conversationId,
-                  lastAppendedMessage ? [lastAppendedMessage] : [],
-                );
+                await persistBootstrapState(conversationId);
 
                 if (importedMessages > 0) {
                   return {
@@ -2090,7 +2715,7 @@ export class LcmContextEngine implements ContextEngine {
 
             if (bootstrapMessages.length === 0) {
               await this.conversationStore.markConversationBootstrapped(conversationId);
-              await persistBootstrapState(conversationId, historicalMessages);
+              await persistBootstrapState(conversationId);
               return {
                 bootstrapped: false,
                 importedMessages: 0,
@@ -2116,18 +2741,19 @@ export class LcmContextEngine implements ContextEngine {
               inserted.map((record) => record.messageId),
             );
             await this.conversationStore.markConversationBootstrapped(conversationId);
-            await persistBootstrapState(conversationId, historicalMessages);
 
             // Prune HEARTBEAT_OK turns from the freshly imported data
             if (this.config.pruneHeartbeatOk) {
               const pruned = await this.pruneHeartbeatOkTurns(conversationId);
               if (pruned > 0) {
-                console.error(
+                this.deps.log.info(
                   `[lcm] bootstrap: pruned ${pruned} HEARTBEAT_OK messages from conversation ${conversationId}`,
                 );
               }
             }
 
+            await persistBootstrapState(conversationId);
+
             return {
               bootstrapped: true,
               importedMessages: inserted.length,
@@ -2143,12 +2769,20 @@ export class LcmContextEngine implements ContextEngine {
             historicalMessages,
           });
 
+          if (reconcile.blockedByImportCap) {
+            return {
+              bootstrapped: false,
+              importedMessages: 0,
+              reason: "reconcile import capped",
+            };
+          }
+
           if (!conversation.bootstrappedAt) {
             await this.conversationStore.markConversationBootstrapped(conversationId);
           }
 
           if (reconcile.importedMessages > 0) {
-            await persistBootstrapState(conversationId, historicalMessages);
+            await persistBootstrapState(conversationId);
             return {
               bootstrapped: true,
               importedMessages: reconcile.importedMessages,
@@ -2157,7 +2791,7 @@ export class LcmContextEngine implements ContextEngine {
           }
 
           if (reconcile.hasOverlap) {
-            await persistBootstrapState(conversationId, historicalMessages);
+            await persistBootstrapState(conversationId);
           }
 
           if (conversation.bootstrappedAt) {
@@ -2189,15 +2823,18 @@ export class LcmContextEngine implements ContextEngine {
         if (conversation) {
           const pruned = await this.pruneHeartbeatOkTurns(conversation.conversationId);
           if (pruned > 0) {
-            console.error(
+            await this.refreshBootstrapState({
+              conversationId: conversation.conversationId,
+              sessionFile: params.sessionFile,
+            });
+            this.deps.log.info(
               `[lcm] bootstrap: retroactively pruned ${pruned} HEARTBEAT_OK messages from conversation ${conversation.conversationId}`,
             );
           }
         }
       } catch (err) {
-        console.error(
-          `[lcm] bootstrap: heartbeat pruning failed:`,
-          err instanceof Error ? err.message : err,
+        this.deps.log.warn(
+          `[lcm] bootstrap: heartbeat pruning failed: ${describeLogError(err)}`,
         );
       }
     }
@@ -2405,9 +3042,24 @@ export class LcmContextEngine implements ContextEngine {
           };
         }
 
-        return params.runtimeContext.rewriteTranscriptEntries({
+        const result = await params.runtimeContext.rewriteTranscriptEntries({
           replacements,
         });
+
+        if (result.changed) {
+          try {
+            await this.refreshBootstrapState({
+              conversationId: conversation.conversationId,
+              sessionFile: params.sessionFile,
+            });
+          } catch (e) {
+            this.deps.log.warn(
+              `[lcm] Failed to update bootstrap checkpoint after maintain: ${describeLogError(e)}`,
+            );
+          }
+        }
+
+        return result;
       },
     );
   }
@@ -2594,9 +3246,8 @@ export class LcmContextEngine implements ContextEngine {
       });
     } catch (err) {
       // Never compact a stale or partially ingested frontier.
-      console.error(
-        `[lcm] afterTurn: ingest failed, skipping compaction:`,
-        err instanceof Error ? err.message : err,
+      this.deps.log.error(
+        `[lcm] afterTurn: ingest failed, skipping compaction: ${describeLogError(err)}`,
       );
       return;
     }
@@ -2610,16 +3261,30 @@ export class LcmContextEngine implements ContextEngine {
         if (conversation) {
           const pruned = await this.pruneHeartbeatOkTurns(conversation.conversationId);
           if (pruned > 0) {
-            console.error(
-              `[lcm] afterTurn: pruned ${pruned} heartbeat ack messages from conversation ${conversation.conversationId}`,
+            const sessionContext = this.formatSessionLogContext({
+              conversationId: conversation.conversationId,
+              sessionId: params.sessionId,
+              sessionKey: params.sessionKey,
+            });
+            try {
+              await this.refreshBootstrapState({
+                conversationId: conversation.conversationId,
+                sessionFile: params.sessionFile,
+              });
+            } catch (err) {
+              this.deps.log.warn(
+                `[lcm] afterTurn: heartbeat pruning checkpoint refresh failed for ${sessionContext}: ${describeLogError(err)}`,
+              );
+            }
+            this.deps.log.info(
+              `[lcm] afterTurn: pruned ${pruned} heartbeat ack messages for ${sessionContext}`,
             );
             return;
           }
         }
       } catch (err) {
-        console.error(
-          `[lcm] afterTurn: heartbeat pruning failed:`,
-          err instanceof Error ? err.message : err,
+        this.deps.log.warn(
+          `[lcm] afterTurn: heartbeat pruning failed: ${describeLogError(err)}`,
         );
       }
     }
@@ -2633,16 +3298,41 @@ export class LcmContextEngine implements ContextEngine {
     });
     const tokenBudget = this.applyAssemblyBudgetCap(resolvedTokenBudget ?? DEFAULT_AFTER_TURN_TOKEN_BUDGET);
     if (resolvedTokenBudget === undefined) {
-      console.warn(
+      this.deps.log.warn(
         `[lcm] afterTurn: tokenBudget not provided; using default ${DEFAULT_AFTER_TURN_TOKEN_BUDGET}`,
       );
     }
 
     const liveContextTokens = estimateSessionTokenCountForAfterTurn(params.messages);
+    const conversation = await this.conversationStore.getConversationForSession({
+      sessionId: params.sessionId,
+      sessionKey: params.sessionKey,
+    });
+    if (!conversation) {
+      return;
+    }
+
+    try {
+      const rawLeafTrigger = await this.compaction.evaluateLeafTrigger(conversation.conversationId);
+      await this.updateCompactionTelemetry({
+        conversationId: conversation.conversationId,
+        runtimeContext: asRecord(params.runtimeContext),
+        tokenBudget,
+        rawTokensOutsideTail: rawLeafTrigger.rawTokensOutsideTail,
+      });
+    } catch (err) {
+      this.deps.log.warn(
+        `[lcm] afterTurn: compaction telemetry update failed: ${describeLogError(err)}`,
+      );
+    }
 
     try {
-      const leafTrigger = await this.evaluateLeafTrigger(params.sessionId, params.sessionKey);
-      if (leafTrigger.shouldCompact) {
+      const leafDecision = await this.evaluateIncrementalCompaction({
+        conversationId: conversation.conversationId,
+        tokenBudget,
+        currentTokenCount: liveContextTokens,
+      });
+      if (leafDecision.shouldCompact) {
         this.compactLeafAsync({
           sessionId: params.sessionId,
           sessionKey: params.sessionKey,
@@ -2650,6 +3340,11 @@ export class LcmContextEngine implements ContextEngine {
           tokenBudget,
           currentTokenCount: liveContextTokens,
           legacyParams,
+          maxPasses: leafDecision.maxPasses,
+          leafChunkTokens: leafDecision.leafChunkTokens,
+          fallbackLeafChunkTokens: leafDecision.fallbackLeafChunkTokens,
+          activityBand: leafDecision.activityBand,
+          allowCondensedPasses: leafDecision.allowCondensedPasses,
         }).catch(() => {
           // Leaf compaction is best-effort and should not fail the caller.
         });
@@ -2787,7 +3482,7 @@ export class LcmContextEngine implements ContextEngine {
     return this.compaction.evaluateLeafTrigger(conversation.conversationId);
   }
 
-  /** Run one incremental leaf compaction pass in the per-session queue. */
+  /** Run one or more incremental leaf compaction passes in the per-session queue. */
   async compactLeafAsync(params: {
     sessionId: string;
     sessionKey?: string;
@@ -2801,6 +3496,11 @@ export class LcmContextEngine implements ContextEngine {
     legacyParams?: Record<string, unknown>;
     force?: boolean;
     previousSummaryContent?: string;
+    maxPasses?: number;
+    leafChunkTokens?: number;
+    fallbackLeafChunkTokens?: number[];
+    activityBand?: ActivityBand;
+    allowCondensedPasses?: boolean;
   }): Promise<CompactResult> {
     if (this.isStatelessSession(params.sessionKey)) {
       return {
@@ -2864,38 +3564,114 @@ export class LcmContextEngine implements ContextEngine {
           };
         }
 
-        const leafResult = await this.compaction.compactLeaf({
-          conversationId: conversation.conversationId,
-          tokenBudget,
-          summarize,
-          force: params.force,
-          previousSummaryContent: params.previousSummaryContent,
-          summaryModel,
-        });
+        const storedTokensBefore = await this.summaryStore.getContextTokenCount(
+          conversation.conversationId,
+        );
+        const maxPasses =
+          typeof params.maxPasses === "number" &&
+          Number.isFinite(params.maxPasses) &&
+          params.maxPasses > 0
+            ? Math.floor(params.maxPasses)
+            : 1;
+        const fallbackLeafChunkTokens = Array.isArray(params.fallbackLeafChunkTokens)
+          ? [...new Set(params.fallbackLeafChunkTokens
+            .filter((value): value is number => typeof value === "number" && Number.isFinite(value) && value > 0)
+            .map((value) => Math.floor(value)))]
+              .sort((a, b) => b - a)
+          : [];
+        let activeLeafChunkTokens =
+          typeof params.leafChunkTokens === "number" &&
+          Number.isFinite(params.leafChunkTokens) &&
+          params.leafChunkTokens > 0
+            ? Math.floor(params.leafChunkTokens)
+            : fallbackLeafChunkTokens[0];
+        this.deps.log.info(
+          `[lcm] compactLeafAsync start: conversation=${conversation.conversationId} session=${params.sessionId} leafChunkTokens=${activeLeafChunkTokens ?? "null"} fallbackLeafChunkTokens=${fallbackLeafChunkTokens.join(",")} maxPasses=${maxPasses} activityBand=${params.activityBand ?? "unknown"} allowCondensedPasses=${params.allowCondensedPasses !== false}`,
+        );
+
+        let rounds = 0;
+        let finalTokens = observedTokens ?? storedTokensBefore;
+        let authFailure = false;
+
+        for (let pass = 0; pass < maxPasses; pass += 1) {
+          let leafResult: Awaited<ReturnType<typeof this.compaction.compactLeaf>> | undefined;
+          while (true) {
+            try {
+              leafResult = await this.compaction.compactLeaf({
+                conversationId: conversation.conversationId,
+                tokenBudget,
+                summarize,
+                ...(activeLeafChunkTokens !== undefined ? { leafChunkTokens: activeLeafChunkTokens } : {}),
+                force: params.force,
+                previousSummaryContent: pass === 0 ? params.previousSummaryContent : undefined,
+                summaryModel,
+                allowCondensedPasses: params.allowCondensedPasses,
+              });
+              break;
+            } catch (err) {
+              const nextLeafChunkTokens = fallbackLeafChunkTokens.find(
+                (value) => activeLeafChunkTokens !== undefined && value < activeLeafChunkTokens,
+              );
+              if (!this.isRecoverableLeafChunkOverflowError(err) || nextLeafChunkTokens === undefined) {
+                throw err;
+              }
+              this.deps.log.warn(
+                `[lcm] compactLeafAsync: retrying with smaller leafChunkTokens=${nextLeafChunkTokens} after provider token-limit error: ${err instanceof Error ? err.message : String(err)}`,
+              );
+              activeLeafChunkTokens = nextLeafChunkTokens;
+            }
+          }
+          if (!leafResult) {
+            break;
+          }
+          finalTokens = leafResult.tokensAfter;
+
+          if (leafResult.authFailure) {
+            authFailure = true;
+            break;
+          }
+          if (!leafResult.actionTaken) {
+            break;
+          }
+          rounds += 1;
+          if (leafResult.tokensAfter >= leafResult.tokensBefore) {
+            break;
+          }
+        }
 
-        if (leafResult.authFailure && breakerKey) {
+        if (authFailure && breakerKey) {
           this.recordCompactionAuthFailure(breakerKey);
-        } else if (leafResult.actionTaken && breakerKey) {
+        } else if (rounds > 0 && breakerKey) {
           this.recordCompactionSuccess(breakerKey);
         }
+        if (rounds > 0) {
+          await this.markLeafCompactionTelemetrySuccess({
+            conversationId: conversation.conversationId,
+            activityBand: params.activityBand,
+          });
+        }
 
-        const tokensBefore = observedTokens ?? leafResult.tokensBefore;
+        const tokensBefore = observedTokens ?? storedTokensBefore;
+        this.deps.log.debug(
+          `[lcm] compactLeafAsync result: conversation=${conversation.conversationId} session=${params.sessionId} rounds=${rounds} compacted=${rounds > 0} authFailure=${authFailure} finalLeafChunkTokens=${activeLeafChunkTokens ?? "null"} finalTokens=${finalTokens}`,
+        );
 
         return {
           ok: true,
-          compacted: leafResult.actionTaken,
-          reason: leafResult.authFailure
+          compacted: rounds > 0,
+          reason: authFailure
             ? "provider auth failure"
-            : leafResult.actionTaken
+            : rounds > 0
               ? "compacted"
               : "below threshold",
           result: {
             tokensBefore,
-            tokensAfter: leafResult.tokensAfter,
+            tokensAfter: finalTokens,
             details: {
-              rounds: leafResult.actionTaken ? 1 : 0,
+              rounds,
               targetTokens: tokenBudget,
               mode: "leaf",
+              maxPasses,
             },
           },
         };
@@ -3024,7 +3800,7 @@ export class LcmContextEngine implements ContextEngine {
         // overflow counts can drive recovery even when persisted context is already small.
         const useSweep = manualCompactionRequested || params.compactionTarget === "threshold";
         if (useSweep) {
-          const sweepResult = await this.compaction.compactFullSweep({
+          const sweepResult = await this.compaction.compact({
             conversationId,
             tokenBudget,
             summarize,
@@ -3038,6 +3814,9 @@ export class LcmContextEngine implements ContextEngine {
           } else if (sweepResult.actionTaken && breakerKey) {
             this.recordCompactionSuccess(breakerKey);
           }
+          if (sweepResult.actionTaken) {
+            await this.markLeafCompactionTelemetrySuccess({ conversationId });
+          }
 
           return {
             ok: !sweepResult.authFailure && (sweepResult.actionTaken || !liveContextStillExceedsTarget),
@@ -3087,6 +3866,9 @@ export class LcmContextEngine implements ContextEngine {
         }
 
         const didCompact = compactResult.rounds > 0;
+        if (didCompact) {
+          await this.markLeafCompactionTelemetrySuccess({ conversationId });
+        }
 
         return {
           ok: compactResult.success,
@@ -3219,6 +4001,69 @@ export class LcmContextEngine implements ContextEngine {
     // The shared connection is managed for the lifetime of the plugin process.
   }
 
+  /** Detect the empty replacement row created during a prior lifecycle rollover. */
+  private async isFreshLifecycleConversation(conversation: ConversationRecord): Promise<boolean> {
+    const currentMessageCount = await this.conversationStore.getMessageCount(conversation.conversationId);
+    if (currentMessageCount !== 0) {
+      return false;
+    }
+    const currentContextItems = await this.summaryStore.getContextItems(conversation.conversationId);
+    return currentContextItems.length === 0 && !conversation.bootstrappedAt;
+  }
+
+  /**
+   * Archive the current active conversation and optionally create the replacement
+   * row that bootstrap should attach to for the next session transcript.
+   */
+  private async applySessionReplacement(params: {
+    reason: string;
+    sessionId?: string;
+    sessionKey?: string;
+    nextSessionId?: string;
+    nextSessionKey?: string;
+    createReplacement: boolean;
+    createReplacementWhenMissing?: boolean;
+  }): Promise<void> {
+    const current = await this.conversationStore.getConversationForSession({
+      sessionId: params.sessionId,
+      sessionKey: params.sessionKey,
+    });
+    if (!current && !params.createReplacementWhenMissing) {
+      return;
+    }
+
+    if (current?.active) {
+      if (params.createReplacement && await this.isFreshLifecycleConversation(current)) {
+        this.deps.log.info(
+          `[lcm] ${params.reason} lifecycle no-op for already fresh conversation ${current.conversationId}`,
+        );
+        return;
+      }
+      await this.conversationStore.archiveConversation(current.conversationId);
+    }
+
+    if (!params.createReplacement) {
+      this.deps.log.info(
+        `[lcm] ${params.reason} lifecycle archived conversation ${current?.conversationId ?? "(none)"}`,
+      );
+      return;
+    }
+
+    const nextSessionId = params.nextSessionId?.trim() || params.sessionId?.trim() || current?.sessionId;
+    if (!nextSessionId) {
+      this.deps.log.warn(`[lcm] ${params.reason} lifecycle skipped: no session identity available`);
+      return;
+    }
+    const nextSessionKey = params.nextSessionKey?.trim() || params.sessionKey?.trim() || current?.sessionKey;
+    const freshConversation = await this.conversationStore.createConversation({
+      sessionId: nextSessionId,
+      ...(nextSessionKey ? { sessionKey: nextSessionKey } : {}),
+    });
+    this.deps.log.info(
+      `[lcm] ${params.reason} lifecycle archived prior conversation and created ${freshConversation.conversationId}`,
+    );
+  }
+
   /** Apply LCM lifecycle semantics for OpenClaw's /new and /reset commands. */
   async handleBeforeReset(params: {
     reason?: string;
@@ -3261,44 +4106,50 @@ export class LcmContextEngine implements ContextEngine {
             );
             return;
           }
-
-          const current = await this.conversationStore.getConversationForSession({
+          await this.applySessionReplacement({
+            reason: "/reset",
             sessionId: params.sessionId,
             sessionKey: params.sessionKey,
+            createReplacement: true,
+            createReplacementWhenMissing: true,
           });
-          if (current?.active) {
-            const currentMessageCount = await this.conversationStore.getMessageCount(
-              current.conversationId,
-            );
-            const currentContextItems = await this.summaryStore.getContextItems(
-              current.conversationId,
-            );
-            if (
-              currentMessageCount === 0
-              && currentContextItems.length === 0
-              && !current.bootstrappedAt
-            ) {
-              this.deps.log.info(
-                `[lcm] /reset no-op for already fresh conversation ${current.conversationId}`,
-              );
-              return;
-            }
-            await this.conversationStore.archiveConversation(current.conversationId);
-          }
+        }),
+    );
+  }
 
-          const nextSessionId = params.sessionId?.trim() || current?.sessionId;
-          if (!nextSessionId) {
-            this.deps.log.warn("[lcm] /reset skipped: no session identity available");
-            return;
-          }
+  /** Apply generic lifecycle semantics for session rollover and deletion hooks. */
+  async handleSessionEnd(params: {
+    reason?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    nextSessionId?: string;
+    nextSessionKey?: string;
+  }): Promise<void> {
+    const reason = params.reason?.trim();
+    if (!reason || reason === "new" || reason === "unknown") {
+      return;
+    }
+    if (this.shouldIgnoreSession({ sessionId: params.sessionId, sessionKey: params.sessionKey })) {
+      return;
+    }
+    if (this.isStatelessSession(params.sessionKey ?? params.nextSessionKey)) {
+      return;
+    }
 
-          const freshConversation = await this.conversationStore.createConversation({
-            sessionId: nextSessionId,
-            sessionKey: params.sessionKey?.trim(),
+    const createReplacement = reason !== "deleted";
+    this.ensureMigrated();
+    await this.withSessionQueue(
+      this.resolveSessionQueueKey(params.nextSessionId ?? params.sessionId, params.sessionKey ?? params.nextSessionKey),
+      async () =>
+        this.conversationStore.withTransaction(async () => {
+          await this.applySessionReplacement({
+            reason: `session_end:${reason}`,
+            sessionId: params.sessionId,
+            sessionKey: params.sessionKey ?? params.nextSessionKey,
+            nextSessionId: params.nextSessionId,
+            nextSessionKey: params.nextSessionKey,
+            createReplacement,
           });
-          this.deps.log.info(
-            `[lcm] /reset archived prior conversation and created ${freshConversation.conversationId}`,
-          );
         }),
     );
   }
@@ -3317,6 +4168,10 @@ export class LcmContextEngine implements ContextEngine {
     return this.summaryStore;
   }
 
+  getCompactionTelemetryStore(): CompactionTelemetryStore {
+    return this.compactionTelemetryStore;
+  }
+
   // ── Heartbeat pruning ──────────────────────────────────────────────────
 
   /**
@@ -3446,3 +4301,6 @@ function createEmergencyFallbackSummarize(): (
     return text.slice(0, maxChars) + "\n[Truncated for context management]";
   };
 }
+
+/** @internal Exposed for unit tests only. */
+export const __testing = { readLastJsonlEntryBeforeOffset };