@martian-engineering/lossless-claw 0.6.2 → 0.7.0

package/src/compaction.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { ConversationStore, CreateMessagePartInput } from "./store/conversation-store.js";
 import type { SummaryStore, SummaryRecord, ContextItemRecord } from "./store/summary-store.js";
 import { extractFileIdsFromContent } from "./large-files.js";
+import { NOOP_LCM_LOGGER, type LcmLogger } from "./lcm-log.js";
 import { LcmProviderAuthError } from "./summarize.js";
 
 // ── Public types ─────────────────────────────────────────────────────────────
@@ -68,7 +69,14 @@ type CompactionSummarizeFn = (
   aggressive?: boolean,
   options?: CompactionSummarizeOptions,
 ) => Promise<string>;
-type PassResult = { summaryId: string; level: CompactionLevel };
+type PassResult = {
+  summaryId: string;
+  level: CompactionLevel;
+  /** Token count of source items removed from context. */
+  removedTokens: number;
+  /** Token count of the newly created summary. */
+  addedTokens: number;
+};
 type LeafChunkSelection = {
   items: ContextItemRecord[];
   rawTokensOutsideTail: number;
@@ -335,12 +343,59 @@ function isMediaAttachmentPart(part: CreateMessagePartInput | { partType: string
 // ── CompactionEngine ─────────────────────────────────────────────────────────
 
 export class CompactionEngine {
+  /**
+   * Per-conversation context items cache, active only during compaction
+   * entry points. null when inactive — external callers (e.g., engine.ts
+   * evaluateLeafTrigger) get uncached reads.
+   *
+   * Uses a reference count so concurrent compactions on different
+   * conversations don't interfere: each withContextCache increments
+   * on entry and decrements on exit; the cache is only destroyed
+   * when all users have exited.
+   */
+  private _contextItemsCache: Map<number, ContextItemRecord[]> | null = null;
+  private _contextItemsCacheRefCount = 0;
+
   constructor(
     private conversationStore: ConversationStore,
     private summaryStore: SummaryStore,
     private config: CompactionConfig,
+    private log: LcmLogger = NOOP_LCM_LOGGER,
   ) {}
 
+  /** Read context items, using per-phase cache when active. */
+  private async getContextItemsCached(conversationId: number): Promise<ContextItemRecord[]> {
+    if (this._contextItemsCache) {
+      if (this._contextItemsCache.has(conversationId)) {
+        return this._contextItemsCache.get(conversationId)!;
+      }
+      const items = await this.summaryStore.getContextItems(conversationId);
+      this._contextItemsCache.set(conversationId, items);
+      return items;
+    }
+    return this.summaryStore.getContextItems(conversationId);
+  }
+
+  /** Invalidate cache for a conversation after context mutation. */
+  private invalidateContextCache(conversationId: number): void {
+    this._contextItemsCache?.delete(conversationId);
+  }
+
+  /** Execute with context cache active. Reference-counted for concurrent use. */
+  private async withContextCache<T>(fn: () => Promise<T>): Promise<T> {
+    if (!this._contextItemsCache) this._contextItemsCache = new Map();
+    this._contextItemsCacheRefCount++;
+    try {
+      return await fn();
+    } finally {
+      this._contextItemsCacheRefCount--;
+      if (this._contextItemsCacheRefCount <= 0) {
+        this._contextItemsCache = null;
+        this._contextItemsCacheRefCount = 0;
+      }
+    }
+  }
+
   // ── evaluate ─────────────────────────────────────────────────────────────
 
   /** Evaluate whether compaction is needed. */
@@ -383,13 +438,13 @@ export class CompactionEngine {
    * `leafChunkTokens`. This lets callers trigger a soft incremental leaf pass
    * before the full context threshold is breached.
    */
-  async evaluateLeafTrigger(conversationId: number): Promise<{
+  async evaluateLeafTrigger(conversationId: number, leafChunkTokensOverride?: number): Promise<{
     shouldCompact: boolean;
     rawTokensOutsideTail: number;
     threshold: number;
   }> {
     const rawTokensOutsideTail = await this.countRawTokensOutsideFreshTail(conversationId);
-    const threshold = this.resolveLeafChunkTokens();
+    const threshold = this.resolveLeafChunkTokens(leafChunkTokensOverride);
     return {
       shouldCompact: rawTokensOutsideTail >= threshold,
       rawTokensOutsideTail,
@@ -409,7 +464,7 @@ export class CompactionEngine {
     hardTrigger?: boolean;
     summaryModel?: string;
   }): Promise<CompactionResult> {
-    return this.compactFullSweep(input);
+    return this.withContextCache(() => this.compactFullSweep(input));
   }
 
   /**
@@ -421,6 +476,20 @@ export class CompactionEngine {
     conversationId: number;
     tokenBudget: number;
     summarize: CompactionSummarizeFn;
+    leafChunkTokens?: number;
+    force?: boolean;
+    previousSummaryContent?: string;
+    summaryModel?: string;
+    allowCondensedPasses?: boolean;
+  }): Promise<CompactionResult> {
+    return this.withContextCache(() => this._compactLeafImpl(input));
+  }
+
+  private async _compactLeafImpl(input: {
+    conversationId: number;
+    tokenBudget: number;
+    summarize: CompactionSummarizeFn;
+    leafChunkTokens?: number;
     force?: boolean;
     previousSummaryContent?: string;
     summaryModel?: string;
@@ -429,7 +498,7 @@ export class CompactionEngine {
 
     const tokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
     const threshold = Math.floor(this.config.contextThreshold * tokenBudget);
-    const leafTrigger = await this.evaluateLeafTrigger(conversationId);
+    const leafTrigger = await this.evaluateLeafTrigger(conversationId, input.leafChunkTokens);
 
     if (!force && tokensBefore <= threshold && !leafTrigger.shouldCompact) {
       return {
@@ -440,7 +509,7 @@ export class CompactionEngine {
       };
     }
 
-    const leafChunk = await this.selectOldestLeafChunk(conversationId);
+    const leafChunk = await this.selectOldestLeafChunk(conversationId, input.leafChunkTokens);
     if (leafChunk.items.length === 0) {
       return {
         actionTaken: false,
@@ -470,7 +539,8 @@ export class CompactionEngine {
         authFailure: true,
       };
     }
-    const tokensAfterLeaf = await this.summaryStore.getContextTokenCount(conversationId);
+    // Delta tracking: compute token change from pass results instead of re-querying DB
+    const tokensAfterLeaf = tokensBefore - leafResult.removedTokens + leafResult.addedTokens;
 
     await this.persistCompactionEvents({
       conversationId,
@@ -488,7 +558,8 @@ export class CompactionEngine {
 
     const incrementalMaxDepth = this.resolveIncrementalMaxDepth();
     const condensedMinChunkTokens = this.resolveCondensedMinChunkTokens();
-    if (incrementalMaxDepth > 0) {
+    let runningTokens = tokensAfterLeaf;
+    if (incrementalMaxDepth > 0 && input.allowCondensedPasses !== false) {
       for (let targetDepth = 0; targetDepth < incrementalMaxDepth; targetDepth++) {
         const fanout = this.resolveFanoutForDepth(targetDepth, false);
         const chunk = await this.selectOldestChunkAtDepth(conversationId, targetDepth);
@@ -496,7 +567,7 @@ export class CompactionEngine {
           break;
         }
 
-        const passTokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
+        const passTokensBefore = runningTokens;
         const condenseResult = await this.condensedPass(
           conversationId,
           chunk.items,
@@ -507,7 +578,7 @@ export class CompactionEngine {
         if (!condenseResult) {
           break;
         }
-        const passTokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+        const passTokensAfter = passTokensBefore - condenseResult.removedTokens + condenseResult.addedTokens;
         await this.persistCompactionEvents({
           conversationId,
           tokensBefore: passTokensBefore,
@@ -518,6 +589,7 @@ export class CompactionEngine {
         });
 
         tokensAfter = passTokensAfter;
+        runningTokens = passTokensAfter;
         condensed = true;
         createdSummaryId = condenseResult.summaryId;
         level = condenseResult.level;
@@ -568,7 +640,7 @@ export class CompactionEngine {
       };
     }
 
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     if (contextItems.length === 0) {
       return {
         actionTaken: false,
@@ -587,13 +659,16 @@ export class CompactionEngine {
     let hadAuthFailure = false;
 
     // Phase 1: leaf passes over oldest raw chunks outside the protected tail.
+    // Delta tracking: maintain a running token count instead of re-querying DB
+    // after each pass. The arithmetic is exact: tokensAfter = tokensBefore - removed + added.
+    let runningTokens = tokensBefore;
     while (true) {
       const leafChunk = await this.selectOldestLeafChunk(conversationId);
       if (leafChunk.items.length === 0) {
         break;
       }
 
-      const passTokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensBefore = runningTokens;
       const leafResult = await this.leafPass(
         conversationId,
         leafChunk.items,
@@ -605,7 +680,7 @@ export class CompactionEngine {
         hadAuthFailure = true;
         break;
       }
-      const passTokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensAfter = passTokensBefore - leafResult.removedTokens + leafResult.addedTokens;
       await this.persistCompactionEvents({
         conversationId,
         tokensBefore: passTokensBefore,
@@ -619,6 +694,7 @@ export class CompactionEngine {
       createdSummaryId = leafResult.summaryId;
       level = leafResult.level;
       previousSummaryContent = leafResult.content;
+      runningTokens = passTokensAfter;
 
       if (!force && passTokensAfter <= threshold) {
         previousTokens = passTokensAfter;
@@ -640,7 +716,7 @@ export class CompactionEngine {
         break;
       }
 
-      const passTokensBefore = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensBefore = runningTokens;
       const condenseResult = await this.condensedPass(
         conversationId,
         candidate.chunk.items,
@@ -652,7 +728,7 @@ export class CompactionEngine {
         hadAuthFailure = true;
         break;
       }
-      const passTokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+      const passTokensAfter = passTokensBefore - condenseResult.removedTokens + condenseResult.addedTokens;
       await this.persistCompactionEvents({
         conversationId,
         tokensBefore: passTokensBefore,
@@ -666,6 +742,7 @@ export class CompactionEngine {
       condensed = true;
       createdSummaryId = condenseResult.summaryId;
       level = condenseResult.level;
+      runningTokens = passTokensAfter;
 
       if (!force && passTokensAfter <= threshold) {
         previousTokens = passTokensAfter;
@@ -677,7 +754,7 @@ export class CompactionEngine {
       previousTokens = passTokensAfter;
     }
 
-    const tokensAfter = await this.summaryStore.getContextTokenCount(conversationId);
+    const tokensAfter = runningTokens;
 
     return {
       actionTaken,
@@ -700,6 +777,17 @@ export class CompactionEngine {
     currentTokens?: number;
     summarize: CompactionSummarizeFn;
     summaryModel?: string;
+  }): Promise<{ success: boolean; rounds: number; finalTokens: number; authFailure?: boolean }> {
+    return this.withContextCache(() => this._compactUntilUnderImpl(input));
+  }
+
+  private async _compactUntilUnderImpl(input: {
+    conversationId: number;
+    tokenBudget: number;
+    targetTokens?: number;
+    currentTokens?: number;
+    summarize: CompactionSummarizeFn;
+    summaryModel?: string;
   }): Promise<{ success: boolean; rounds: number; finalTokens: number; authFailure?: boolean }> {
     const { conversationId, tokenBudget, summarize } = input;
     const targetTokens =
@@ -763,8 +851,8 @@ export class CompactionEngine {
       lastTokens = result.tokensAfter;
     }
 
-    // Exhausted all rounds
-    const finalTokens = await this.summaryStore.getContextTokenCount(conversationId);
+    // Exhausted all rounds — use the last known token count from compact() result
+    const finalTokens = lastTokens;
     return {
       success: finalTokens <= targetTokens,
       rounds: this.config.maxRounds,
@@ -775,7 +863,14 @@ export class CompactionEngine {
   // ── Private helpers ──────────────────────────────────────────────────────
 
   /** Normalize configured leaf chunk size to a safe positive integer. */
-  private resolveLeafChunkTokens(): number {
+  private resolveLeafChunkTokens(leafChunkTokensOverride?: number): number {
+    if (
+      typeof leafChunkTokensOverride === "number" &&
+      Number.isFinite(leafChunkTokensOverride) &&
+      leafChunkTokensOverride > 0
+    ) {
+      return Math.floor(leafChunkTokensOverride);
+    }
     if (
       typeof this.config.leafChunkTokens === "number" &&
       Number.isFinite(this.config.leafChunkTokens) &&
@@ -838,7 +933,7 @@ export class CompactionEngine {
 
   /** Sum raw message tokens outside the protected fresh tail. */
   private async countRawTokensOutsideFreshTail(conversationId: number): Promise<number> {
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal = this.resolveFreshTailOrdinal(contextItems);
     let rawTokens = 0;
 
@@ -861,10 +956,13 @@ export class CompactionEngine {
    * The selected chunk size is capped by `leafChunkTokens`, but we always pick
    * at least one message when any compactable message exists.
    */
-  private async selectOldestLeafChunk(conversationId: number): Promise<LeafChunkSelection> {
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+  private async selectOldestLeafChunk(
+    conversationId: number,
+    leafChunkTokensOverride?: number,
+  ): Promise<LeafChunkSelection> {
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal = this.resolveFreshTailOrdinal(contextItems);
-    const threshold = this.resolveLeafChunkTokens();
+    const threshold = this.resolveLeafChunkTokens(leafChunkTokensOverride);
 
     let rawTokensOutsideTail = 0;
     for (const item of contextItems) {
@@ -927,7 +1025,7 @@ export class CompactionEngine {
     }
 
     const startOrdinal = Math.min(...messageItems.map((item) => item.ordinal));
-    const priorSummaryItems = (await this.summaryStore.getContextItems(conversationId))
+    const priorSummaryItems = (await this.getContextItemsCached(conversationId))
       .filter(
         (item) =>
           item.ordinal < startOrdinal &&
@@ -1051,7 +1149,7 @@ export class CompactionEngine {
     hardTrigger: boolean;
   }): Promise<CondensedPhaseCandidate | null> {
     const { conversationId, hardTrigger } = params;
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal = this.resolveFreshTailOrdinal(contextItems);
     const minChunkTokens = this.resolveCondensedMinChunkTokens();
     const depthLevels = await this.summaryStore.getDistinctDepthsInContext(conversationId, {
@@ -1088,7 +1186,7 @@ export class CompactionEngine {
     targetDepth: number,
     freshTailOrdinalOverride?: number,
   ): Promise<CondensedChunkSelection> {
-    const contextItems = await this.summaryStore.getContextItems(conversationId);
+    const contextItems = await this.getContextItemsCached(conversationId);
     const freshTailOrdinal =
       typeof freshTailOrdinalOverride === "number"
         ? freshTailOrdinalOverride
@@ -1147,7 +1245,7 @@ export class CompactionEngine {
     }
 
     const startOrdinal = Math.min(...summaryItems.map((item) => item.ordinal));
-    const priorSummaryItems = (await this.summaryStore.getContextItems(conversationId))
+    const priorSummaryItems = (await this.getContextItemsCached(conversationId))
       .filter(
         (item) =>
           item.ordinal < startOrdinal &&
@@ -1264,7 +1362,7 @@ export class CompactionEngine {
     const maxTokens = Math.ceil(params.targetTokens * this.config.summaryMaxOverageFactor);
 
     if (summaryTokens > Math.ceil(params.targetTokens * 1.5)) {
-      console.warn(
+      this.log.warn(
         `[lcm] summary exceeds target by ${Math.round((summaryTokens / params.targetTokens - 1) * 100)}%: ${summaryTokens} tokens vs target ${params.targetTokens}`,
       );
     }
@@ -1330,7 +1428,7 @@ export class CompactionEngine {
     summarize: CompactionSummarizeFn,
     previousSummaryContent?: string,
     summaryModel?: string,
-  ): Promise<{ summaryId: string; level: CompactionLevel; content: string } | null> {
+  ): Promise<{ summaryId: string; level: CompactionLevel; content: string; removedTokens: number; addedTokens: number } | null> {
     // Fetch full message content for each context item
     const messageContents: { messageId: number; content: string; createdAt: Date; tokenCount: number }[] =
       [];
@@ -1369,7 +1467,7 @@ export class CompactionEngine {
       targetTokens: this.config.leafTargetTokens,
     });
     if (!summary) {
-      console.warn(
+      this.log.warn(
         `[lcm] leaf compaction skipped summary write; conversationId=${conversationId}; chunkMessages=${messageContents.length}`,
       );
       return null;
@@ -1378,6 +1476,16 @@ export class CompactionEngine {
     // Persist the leaf summary
     const summaryId = generateSummaryId(summary.content);
     const tokenCount = estimateTokens(summary.content);
+    // Note: removedTokens uses resolveMessageTokenCount values (which fall back to
+    // estimateTokens for messages with token_count <= 0). This can diverge from
+    // getContextTokenCount() which would sum the stored 0. The delta feeds into
+    // stopping decisions (threshold checks, progress guards), but the divergence
+    // is bounded to empty/corrupt messages (token_count=0) which are rare.
+    // For summaries, removedTokens matches the DB exactly (same tokenCount column).
+    const removedTokens = messageContents.reduce(
+      (sum, message) => sum + Math.max(0, Math.floor(message.tokenCount)),
+      0,
+    );
 
     await this.summaryStore.withTransaction(async () => {
       await this.summaryStore.insertSummary({
@@ -1398,10 +1506,7 @@ export class CompactionEngine {
             : undefined,
         descendantCount: 0,
         descendantTokenCount: 0,
-        sourceMessageTokenCount: messageContents.reduce(
-          (sum, message) => sum + Math.max(0, Math.floor(message.tokenCount)),
-          0,
-        ),
+        sourceMessageTokenCount: removedTokens,
         model: summaryModel,
       });
 
@@ -1421,8 +1526,9 @@ export class CompactionEngine {
         summaryId,
       });
     });
+    this.invalidateContextCache(conversationId);
 
-    return { summaryId, level: summary.level, content: summary.content };
+    return { summaryId, level: summary.level, content: summary.content, removedTokens, addedTokens: tokenCount };
   }
 
   // ── Private: Condensed Pass ──────────────────────────────────────────────
@@ -1479,7 +1585,7 @@ export class CompactionEngine {
       targetTokens: this.config.condensedTargetTokens,
     });
     if (!condensed) {
-      console.warn(
+      this.log.warn(
         `[lcm] condensed compaction skipped summary write; conversationId=${conversationId}; depth=${targetDepth}; chunkSummaries=${summaryRecords.length}`,
       );
       return null;
@@ -1560,8 +1666,13 @@ export class CompactionEngine {
         summaryId,
       });
     });
+    this.invalidateContextCache(conversationId);
 
-    return { summaryId, level: condensed.level };
+    const removedTokens = summaryRecords.reduce(
+      (sum, s) => sum + Math.max(0, Math.floor(s.tokenCount)),
+      0,
+    );
+    return { summaryId, level: condensed.level, removedTokens, addedTokens: tokenCount };
   }
 
   /** Emit compaction telemetry without mutating canonical conversation history. */
@@ -1638,7 +1749,7 @@ export class CompactionEngine {
     condensedPassOccurred: boolean;
   }): Promise<void> {
     const content = `LCM compaction ${input.pass} pass (${input.level}): ${input.tokensBefore} -> ${input.tokensAfter}`;
-    console.info(
+    this.log.info(
       `[lcm] ${content} conversation=${input.conversationId} summary=${input.createdSummaryId}`,
     );
   }

package/src/db/config.ts

@@ -1,6 +1,18 @@
 import { homedir } from "os";
 import { join } from "path";
 
+export type CacheAwareCompactionConfig = {
+  enabled: boolean;
+  maxColdCacheCatchupPasses: number;
+  hotCachePressureFactor: number;
+  hotCacheBudgetHeadroomRatio: number;
+};
+
+export type DynamicLeafChunkTokensConfig = {
+  enabled: boolean;
+  max: number;
+};
+
 export type LcmConfig = {
   enabled: boolean;
   databasePath: string;
@@ -32,10 +44,6 @@ export type LcmConfig = {
   largeFileSummaryProvider: string;
   /** Model override for large-file text summarization. */
   largeFileSummaryModel: string;
-  /** Model override for conversation summarization. */
-  summaryModel: string;
-  /** Provider override for conversation summarization. */
-  summaryProvider: string;
   /** Provider override for lcm_expand_query sub-agent. */
   expansionProvider: string;
   /** Model override for lcm_expand_query sub-agent. */
@@ -58,6 +66,12 @@ export type LcmConfig = {
   circuitBreakerThreshold: number;
   /** Cooldown in milliseconds before the circuit breaker auto-resets (default 30 min). */
   circuitBreakerCooldownMs: number;
+  /** Explicit fallback provider/model pairs for compaction summarization. */
+  fallbackProviders: Array<{ provider: string; model: string }>;
+  /** Cache-sensitive policy for incremental leaf compaction. */
+  cacheAwareCompaction: CacheAwareCompactionConfig;
+  /** Dynamic step-band policy for incremental leaf chunk sizing. */
+  dynamicLeafChunkTokens: DynamicLeafChunkTokensConfig;
 };
 
 /** Safely coerce an unknown value to a finite number, or return undefined. */
@@ -85,6 +99,39 @@ function parseFiniteNumber(value: string | undefined): number | undefined {
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+/** Parse fallback providers from env string (format: "provider/model,provider/model"). */
+function parseFallbackProviders(value: string | undefined): Array<{ provider: string; model: string }> | undefined {
+  if (!value?.trim()) return undefined;
+  const entries: Array<{ provider: string; model: string }> = [];
+  for (const part of value.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const slashIdx = trimmed.indexOf("/");
+    if (slashIdx > 0 && slashIdx < trimmed.length - 1) {
+      const provider = trimmed.slice(0, slashIdx).trim();
+      const model = trimmed.slice(slashIdx + 1).trim();
+      if (provider && model) {
+        entries.push({ provider, model });
+      }
+    }
+  }
+  return entries.length > 0 ? entries : undefined;
+}
+
+/** Parse fallback providers from plugin config array (object items only). */
+function toFallbackProviderArray(value: unknown): Array<{ provider: string; model: string }> | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const entries: Array<{ provider: string; model: string }> = [];
+  for (const item of value) {
+    if (item && typeof item === "object" && !Array.isArray(item)) {
+      const p = toStr((item as Record<string, unknown>).provider);
+      const m = toStr((item as Record<string, unknown>).model);
+      if (p && m) entries.push({ provider: p, model: m });
+    }
+  }
+  return entries.length > 0 ? entries : undefined;
+}
+
 /** Safely coerce an unknown value to a boolean, or return undefined. */
 function toBool(value: unknown): boolean | undefined {
   if (typeof value === "boolean") return value;
@@ -120,6 +167,12 @@ function toStrArray(value: unknown): string[] | undefined {
     .filter(Boolean);
 }
 
+function toRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
 /**
  * Resolve LCM configuration with three-tier precedence:
  *   1. Environment variables (highest — backward compat)
@@ -131,6 +184,8 @@ export function resolveLcmConfig(
   pluginConfig?: Record<string, unknown>,
 ): LcmConfig {
   const pc = pluginConfig ?? {};
+  const cacheAwareCompaction = toRecord(pc.cacheAwareCompaction);
+  const dynamicLeafChunkTokens = toRecord(pc.dynamicLeafChunkTokens);
   const resolvedLeafChunkTokens =
     parseFiniteInt(env.LCM_LEAF_CHUNK_TOKENS)
       ?? toNumber(pc.leafChunkTokens) ?? 20000;
@@ -142,6 +197,27 @@ export function resolveLcmConfig(
     env.LCM_DELEGATION_TIMEOUT_MS !== undefined
       ? toNumber(env.LCM_DELEGATION_TIMEOUT_MS)
       : undefined;
+  const resolvedDynamicLeafChunkMax = Math.max(
+    resolvedLeafChunkTokens,
+    parseFiniteInt(env.LCM_DYNAMIC_LEAF_CHUNK_TOKENS_MAX)
+      ?? toNumber(dynamicLeafChunkTokens?.max)
+      ?? Math.floor(resolvedLeafChunkTokens * 2),
+  );
+  const resolvedHotCachePressureFactor = Math.max(
+    1,
+    parseFiniteNumber(env.LCM_HOT_CACHE_PRESSURE_FACTOR)
+      ?? toNumber(cacheAwareCompaction?.hotCachePressureFactor)
+      ?? 4,
+  );
+  const resolvedHotCacheBudgetHeadroomRatio = Math.min(
+    0.95,
+    Math.max(
+      0,
+      parseFiniteNumber(env.LCM_HOT_CACHE_BUDGET_HEADROOM_RATIO)
+        ?? toNumber(cacheAwareCompaction?.hotCacheBudgetHeadroomRatio)
+        ?? 0.2,
+    ),
+  );
 
   return {
     enabled:
@@ -243,5 +319,27 @@ export function resolveLcmConfig(
     circuitBreakerCooldownMs:
       parseFiniteInt(env.LCM_CIRCUIT_BREAKER_COOLDOWN_MS)
         ?? toNumber(pc.circuitBreakerCooldownMs) ?? 1_800_000,
+    fallbackProviders:
+      parseFallbackProviders(env.LCM_FALLBACK_PROVIDERS)
+        ?? toFallbackProviderArray(pc.fallbackProviders) ?? [],
+    cacheAwareCompaction: {
+      enabled:
+        env.LCM_CACHE_AWARE_COMPACTION_ENABLED !== undefined
+          ? env.LCM_CACHE_AWARE_COMPACTION_ENABLED !== "false"
+          : toBool(cacheAwareCompaction?.enabled) ?? true,
+      maxColdCacheCatchupPasses:
+        parseFiniteInt(env.LCM_MAX_COLD_CACHE_CATCHUP_PASSES)
+          ?? toNumber(cacheAwareCompaction?.maxColdCacheCatchupPasses)
+          ?? 2,
+      hotCachePressureFactor: resolvedHotCachePressureFactor,
+      hotCacheBudgetHeadroomRatio: resolvedHotCacheBudgetHeadroomRatio,
+    },
+    dynamicLeafChunkTokens: {
+      enabled:
+        env.LCM_DYNAMIC_LEAF_CHUNK_TOKENS_ENABLED !== undefined
+          ? env.LCM_DYNAMIC_LEAF_CHUNK_TOKENS_ENABLED === "true"
+          : toBool(dynamicLeafChunkTokens?.enabled) ?? true,
+      max: resolvedDynamicLeafChunkMax,
+    },
   };
 }

package/src/db/connection.ts

@@ -13,7 +13,7 @@ function isInMemoryPath(dbPath: string): boolean {
   return normalized === ":memory:" || normalized.startsWith("file::memory:");
 }
 
-function normalizePath(dbPath: string): ConnectionKey {
+export function normalizePath(dbPath: string): ConnectionKey {
   if (isInMemoryPath(dbPath)) {
     const trimmed = dbPath.trim();
     return trimmed.length > 0 ? trimmed : ":memory:";
@@ -32,6 +32,15 @@ function configureConnection(db: DatabaseSync): DatabaseSync {
   db.exec("PRAGMA journal_mode = WAL");
   db.exec(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`);
   db.exec("PRAGMA foreign_keys = ON");
+  // 64MB page cache (default 2MB is severely undersized for multi-GB databases
+  // with concurrent agents). Memory is demand-allocated, released on close.
+  db.exec("PRAGMA cache_size = -65536");
+  // NORMAL is officially recommended for WAL mode — crash-safe for app crashes,
+  // only risks data loss on power failure (OS/kernel crash). The bootstrap
+  // process re-ingests any lost transactions from session files.
+  db.exec("PRAGMA synchronous = NORMAL");
+  // Keep temp tables/indexes in RAM (helps ordinal resequencing).
+  db.exec("PRAGMA temp_store = MEMORY");
   return db;
 }
 
@@ -66,6 +75,9 @@ function closeDatabase(db: DatabaseSync | undefined): void {
     return;
   }
   try {
+    // Update query planner statistics for tables that changed since last optimize.
+    // Separate try so a SQLITE_BUSY/SQLITE_READONLY from optimize doesn't skip close.
+    try { db.exec("PRAGMA optimize"); } catch { /* best-effort */ }
     db.close();
   } catch {
     // Ignore close failures; callers are shutting down anyway.
@@ -81,7 +93,13 @@ function closeDatabase(db: DatabaseSync | undefined): void {
  */
 export function createLcmDatabaseConnection(dbPath: string): DatabaseSync {
   ensureDbDirectory(dbPath);
-  const db = configureConnection(new DatabaseSync(dbPath));
+  const db = new DatabaseSync(dbPath);
+  try {
+    configureConnection(db);
+  } catch (err) {
+    try { db.close(); } catch { /* ignore cleanup failure */ }
+    throw err;
+  }
   trackConnection(dbPath, db);
   return db;
 }