@psiclawops/hypermem 0.8.5 → 0.9.0

package/plugin/dist/index.js

@@ -22,12 +22,15 @@
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
 import { buildPluginConfigSchema } from 'openclaw/plugin-sdk/core';
 import { z } from 'zod';
-import { detectTopicShift, stripMessageMetadata, SessionTopicMap, applyToolGradientToWindow, OPENCLAW_BOOTSTRAP_FILES, rotateSessionContext, TRIM_SOFT_TARGET, TRIM_GROWTH_THRESHOLD, TRIM_HEADROOM_FRACTION, resolveTrimBudgets, formatToolChainStub, decideReplayRecovery, isReplayState, } from '@psiclawops/hypermem';
+import { detectTopicShift, stripMessageMetadata, SessionTopicMap, applyToolGradientToWindow, OPENCLAW_BOOTSTRAP_FILES, rotateSessionContext, TRIM_SOFT_TARGET, TRIM_GROWTH_THRESHOLD, TRIM_HEADROOM_FRACTION, resolveTrimBudgets, resolveAdaptiveLifecyclePolicy, formatToolChainStub, decideReplayRecovery, isReplayState, recordOutputMetrics, 
+// Sprint 3: unified pressure signal
+computeUnifiedPressure, PRESSURE_SOURCE, } from '@psiclawops/hypermem';
 import { evictStaleContent } from '@psiclawops/hypermem/image-eviction';
 import { repairToolPairs } from '@psiclawops/hypermem';
 import os from 'os';
 import path from 'path';
 import fs from 'fs/promises';
+import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'url';
 import fsSync from 'fs';
 let _telemetryStream = null;
@@ -107,6 +110,24 @@ function degradationTelemetry(fields) {
         // Telemetry must never throw
     }
 }
+function lifecyclePolicyTelemetry(fields) {
+    if (!telemetryEnabled())
+        return;
+    const stream = getTelemetryStream();
+    if (!stream)
+        return;
+    try {
+        const record = {
+            event: 'lifecycle-policy',
+            ts: new Date().toISOString(),
+            ...fields,
+        };
+        stream.write(JSON.stringify(record) + '\n');
+    }
+    catch {
+        // Telemetry must never throw
+    }
+}
 function nextTurnId() {
     _telemetryTurnCounter = (_telemetryTurnCounter + 1) >>> 0;
     return `${Date.now().toString(36)}-${_telemetryTurnCounter.toString(36)}`;
@@ -279,6 +300,7 @@ export const __telemetryForTests = {
     assembleTrace,
     degradationTelemetry,
     guardTelemetry,
+    lifecyclePolicyTelemetry,
     nextTurnId,
     beginTrimOwnerTurn,
     endTrimOwnerTurn,
@@ -464,6 +486,7 @@ function resolveConfiguredWindow(model) {
 // Subagent warming mode: 'full' | 'light' | 'off'. Default: 'light'.
 // Controls how much HyperMem context is injected into subagent sessions.
 let _subagentWarming = 'light';
+const FORKED_CONTEXT_META_SLOT = 'forkedContextMeta';
 // Cache replay threshold: 15min default. Set to 0 in user config to disable.
 let _cacheReplayThresholdMs = 900_000;
 // ─── System overhead cache ────────────────────────────────────
@@ -579,6 +602,8 @@ async function loadUserConfig() {
         merged.eviction = { ...merged.eviction, ..._pluginConfig.eviction };
     if (_pluginConfig.embedding)
         merged.embedding = { ...merged.embedding, ..._pluginConfig.embedding };
+    if (_pluginConfig.reranker)
+        merged.reranker = { ...merged.reranker, ..._pluginConfig.reranker };
     if (Object.keys(fileConfig).length > 0 && Object.keys(_pluginConfig).filter(k => k !== 'hyperMemPath' && k !== 'dataDir').length > 0) {
         console.log('[hypermem-plugin] Note: migrating config.json keys to plugins.entries.hypercompositor.config in openclaw.json is recommended');
     }
@@ -663,15 +688,19 @@ async function getHyperMem() {
             `effective history budget: ${_contextWindowSize - reservedTokens} tokens`);
         verboseLog(`[hypermem-plugin] warmCacheReplayThresholdMs=${_cacheReplayThresholdMs}`);
         verboseLog(`[hypermem-plugin] contextWindowOverrides keys=${Object.keys(_contextWindowOverrides).join(', ') || '(none)'}`);
+        const cacheConfig = userConfig.cache;
         const instance = await HyperMem.create({
             dataDir: _pluginConfig.dataDir ?? path.join(os.homedir(), '.openclaw/hypermem'),
             cache: {
-                keyPrefix: 'hm:',
-                sessionTTL: 14400, // 4h for system/identity/meta slots
-                historyTTL: 86400, // 24h for history — ages out, not count-trimmed
+                keyPrefix: cacheConfig?.keyPrefix ?? 'hm:',
+                sessionTTL: cacheConfig?.sessionTTL ?? 14400, // 4h default for system/identity/meta slots
+                historyTTL: cacheConfig?.historyTTL ?? 86400, // 24h default for history/cursor hot cache
             },
             ...(userConfig.compositor ? { compositor: userConfig.compositor } : {}),
             ...(_embeddingConfig ? { embedding: _embeddingConfig } : {}),
+            ...(userConfig.reranker
+                ? { reranker: userConfig.reranker }
+                : {}),
         });
         _hm = instance;
         // Wire up fleet store and background indexer from dynamic module
@@ -790,6 +819,33 @@ function resolveAssistantTokenCount(msg, runtimeContext) {
     }
     return undefined;
 }
+function resolveAssistantOutputTokenCount(msg, runtimeContext) {
+    const usage = msg.usage;
+    if (usage && typeof usage === 'object') {
+        const candidates = [
+            usage.output,
+            usage.outputTokens,
+            usage.output_tokens,
+            usage.completionTokens,
+            usage.completion_tokens,
+            usage.totalTokens,
+            usage.total_tokens,
+            usage.total,
+        ];
+        for (const candidate of candidates) {
+            if (typeof candidate === 'number' && Number.isFinite(candidate) && candidate > 0) {
+                return Math.floor(candidate);
+            }
+        }
+    }
+    const runtimeTokenCount = runtimeContext?.currentTokenCount;
+    if (typeof runtimeTokenCount === 'number' && Number.isFinite(runtimeTokenCount) && runtimeTokenCount > 0) {
+        return Math.floor(runtimeTokenCount);
+    }
+    const text = extractTextFromInboundContent(msg.content);
+    const tokenEstimate = Math.ceil(text.length / 4);
+    return tokenEstimate > 0 ? tokenEstimate : undefined;
+}
 function collectNeutralToolPairStats(messages) {
     const callIds = new Set();
     const resultIds = new Set();
@@ -1775,7 +1831,9 @@ function createHyperMemEngine() {
                         });
                         const replayMarkerText = replayRecovery.emittedText;
                         const preTrimTokens = runtimeTokens;
-                        const pressure = preTrimTokens / effectiveBudget;
+                        // Sprint 3: unified pressure signal — tool-loop assemble path
+                        const s3ToolLoopPressure = computeUnifiedPressure(preTrimTokens, effectiveBudget, PRESSURE_SOURCE.TOOLLOOP_RUNTIME_ARRAY);
+                        const pressure = s3ToolLoopPressure.fraction;
                         // Pressure-tiered trim targets use a single authority: the working
                         // message array. Redis drift is logged as an anomaly, never used as
                         // a trim trigger. Replay recovery gets its own explicit bounded mode
@@ -1927,17 +1985,17 @@ function createHyperMemEngine() {
                             const kept = keptClusters.flat();
                             const keptCount = processedConvMsgs.length - kept.length;
                             if (keptCount > 0) {
-                                console.log(`[hypermem-plugin] tool-loop trim: pressure=${(pressure * 100).toFixed(1)}% → ` +
+                                console.log(`[hypermem-plugin] tool-loop trim: pressure=${s3ToolLoopPressure.pct}% source=${s3ToolLoopPressure.source} → ` +
                                     `target=${(trimTarget * 100).toFixed(0)}% (redis=${trimmed} msgs, messages=${keptCount} dropped)`);
                                 trimmedMessages = [...systemMsgs, ...kept];
                             }
                             else if (trimmed > 0) {
-                                console.log(`[hypermem-plugin] tool-loop trim: pressure=${(pressure * 100).toFixed(1)}% → ` +
+                                console.log(`[hypermem-plugin] tool-loop trim: pressure=${s3ToolLoopPressure.pct}% source=${s3ToolLoopPressure.source} → ` +
                                     `target=${(trimTarget * 100).toFixed(0)}% (redis=${trimmed} msgs)`);
                             }
                         }
                         else if (trimmed > 0) {
-                            console.log(`[hypermem-plugin] tool-loop trim: pressure=${(pressure * 100).toFixed(1)}% → ` +
+                            console.log(`[hypermem-plugin] tool-loop trim: pressure=${s3ToolLoopPressure.pct}% source=${s3ToolLoopPressure.source} → ` +
                                 `target=${(trimTarget * 100).toFixed(0)}% (redis=${trimmed} msgs)`);
                         }
                         // Apply tool gradient to compress large tool results before returning.
@@ -2205,6 +2263,7 @@ function createHyperMemEngine() {
                                             path: 'replay',
                                             toolLoop: isToolLoop,
                                             msgCount: messages.length,
+                                            composeTopicTelemetryStatus: 'intentionally-omitted',
                                         });
                                     }
                                 }
@@ -2217,6 +2276,20 @@ function createHyperMemEngine() {
                     // Subagent light mode: skip library/wiki/semantic/keystones/doc chunks.
                     // Keeps: system, identity, history, active facts, output profile, tool gradient.
                     const subagentLight = isSubagent && _subagentWarming === 'light';
+                    let forkedContext;
+                    if (isSubagent) {
+                        try {
+                            const rawForkedContext = await hm.cache.getSlot(agentId, sk, FORKED_CONTEXT_META_SLOT);
+                            if (rawForkedContext) {
+                                const parsed = JSON.parse(rawForkedContext);
+                                if (parsed?.enabled === true)
+                                    forkedContext = parsed;
+                            }
+                        }
+                        catch {
+                            // Fork metadata is advisory; fall back to normal subagent lifecycle.
+                        }
+                    }
                     const request = {
                         agentId,
                         sessionKey: sk,
@@ -2231,6 +2304,7 @@ function createHyperMemEngine() {
                         includeSemanticRecall: subagentLight ? false : undefined, // skip vector/FTS recall
                         includeKeystones: subagentLight ? false : undefined, // skip keystone history injection
                         prompt,
+                        forkedContext,
                         skipProviderTranslation: true, // runtime handles provider translation
                     };
                     const result = await hm.compose(request);
@@ -2246,6 +2320,63 @@ function createHyperMemEngine() {
                         replayState: replayRecovery.emittedMarker?.state,
                         replayReason: replayRecovery.emittedMarker?.reason,
                     });
+                    // Sprint 1: emit assemble-level trace with full observability fields
+                    // after a full compose (not replay). Surfaces prefix stability,
+                    // reranker outcome, slot spans, and compaction eligibility.
+                    if (telemetryEnabled() && !cachedContextBlock) {
+                        const diag = result.diagnostics;
+                        // prefixChanged: compare current prefixHash against prevPrefixHash
+                        // (surfaced by the compositor when a cache bypass detected prefix mutation).
+                        // When no previous hash is available (first turn), leave prefixChanged undefined.
+                        let prefixChanged;
+                        if (diag?.prefixHash && diag?.prevPrefixHash) {
+                            prefixChanged = diag.prefixHash !== diag.prevPrefixHash;
+                        }
+                        assembleTrace({
+                            agentId,
+                            sessionKey: sk,
+                            turnId: _asmTurnId,
+                            path: isSubagent ? 'subagent' : 'cold',
+                            toolLoop: isToolLoop,
+                            msgCount: result.messages.length,
+                            prefixChanged,
+                            prefixHash: diag?.prefixHash,
+                            rerankerStatus: diag?.rerankerStatus,
+                            rerankerCandidates: diag?.rerankerCandidates,
+                            rerankerProvider: diag?.rerankerProvider,
+                            slotSpans: diag?.slotSpans,
+                            compactionEligibleCount: diag?.compactionEligibleCount,
+                            compactionEligibleRatio: diag?.compactionEligibleRatio,
+                            compactionProcessedCount: diag?.compactionProcessedCount,
+                            composeTopicSource: diag?.composeTopicSource,
+                            composeTopicState: diag?.composeTopicState,
+                            composeTopicMessageCount: diag?.composeTopicMessageCount,
+                            composeTopicStampedMessageCount: diag?.composeTopicStampedMessageCount,
+                            composeTopicTelemetryStatus: diag?.composeTopicTelemetryStatus,
+                        });
+                        if (diag?.adaptiveLifecycleBand) {
+                            lifecyclePolicyTelemetry({
+                                path: 'compose.preRecall',
+                                agentId,
+                                sessionKey: sk,
+                                band: diag.adaptiveLifecycleBand,
+                                pressurePct: diag.adaptiveLifecyclePressurePct,
+                                trimSoftTarget: diag.adaptiveTrimSoftTarget,
+                                reasons: diag.adaptiveLifecycleReasons,
+                            });
+                        }
+                        if (diag?.adaptiveEvictionLifecycleBand) {
+                            lifecyclePolicyTelemetry({
+                                path: 'compose.eviction',
+                                agentId,
+                                sessionKey: sk,
+                                band: diag.adaptiveEvictionLifecycleBand,
+                                pressurePct: diag.adaptiveEvictionPressurePct,
+                                trimSoftTarget: diag.adaptiveTrimSoftTarget,
+                                reasons: diag.adaptiveLifecycleBandDiverged ? ['diverged-from-preRecall'] : undefined,
+                            });
+                        }
+                    }
                     // Use cached contextBlock if available (cache replay), otherwise use fresh result.
                     // After a full compose, write the new contextBlock to cache for the next turn.
                     if (cachedContextBlock) {
@@ -2318,6 +2449,9 @@ ${replayRecovery.emittedText}`
                     const runtimeSystemTokens = getOverheadFallback(tier);
                     _overheadCache.set(sk, contextBlockTokens + runtimeSystemTokens);
                     await persistReplayRecoveryState(hm, agentId, sk, replayRecovery.nextState);
+                    if (forkedContext) {
+                        await hm.cache.setSlot(agentId, sk, FORKED_CONTEXT_META_SLOT, '').catch(() => { });
+                    }
                     // Update model state for downshift detection on next turn
                     try {
                         const modelIdentity = resolveModelIdentity(model);
@@ -2406,6 +2540,9 @@ ${replayRecovery.emittedText}`
                 // budget the history is competing for. We trim history to make room.
                 const effectiveBudget = computeEffectiveBudget(tokenBudget, model);
                 const tokensBefore = await estimateWindowTokens(hm, agentId, sk);
+                // Sprint 3: Unified pressure signal — compact path (Redis estimate)
+                const s3CompactPressure = computeUnifiedPressure(tokensBefore, effectiveBudget, PRESSURE_SOURCE.COMPACT_REDIS_ESTIMATE);
+                console.log(`[hypermem-plugin] compact: pressure=${s3CompactPressure.pct}% source=${s3CompactPressure.source} tokens=${tokensBefore}/${effectiveBudget}`);
                 // Target depth for both Redis trimming and JSONL truncation.
                 // Target 50% of budget capacity, assume ~500 tokens/message average.
                 const targetDepth = Math.max(20, Math.floor((effectiveBudget * 0.5) / 500));
@@ -2419,6 +2556,10 @@ ${replayRecovery.emittedText}`
                 // Also triggered when reshape ran recently but the session is still
                 // critically full — bypass the reshape guard in that case.
                 const NUCLEAR_THRESHOLD = 0.85;
+                // Sprint 3: runtime-total pressure for nuclear check uses its own source label
+                const s3NuclearPressure = currentTokenCount != null
+                    ? computeUnifiedPressure(currentTokenCount, effectiveBudget, PRESSURE_SOURCE.COMPACT_RUNTIME_TOTAL)
+                    : s3CompactPressure;
                 const isNuclear = currentTokenCount != null && currentTokenCount > effectiveBudget * NUCLEAR_THRESHOLD;
                 if (isNuclear) {
                     // Cut deep: target 20% of normal depth = ~25 messages for a 128k session.
@@ -2437,11 +2578,11 @@ ${replayRecovery.emittedText}`
                             postTokens: tokensAfter,
                             removed: nuclearRemoved,
                             cacheInvalidated: true,
-                            reason: `currentTokenCount=${currentTokenCount}/${effectiveBudget}`,
+                            reason: `${s3NuclearPressure.source}:${s3NuclearPressure.pct}% currentTokenCount=${currentTokenCount}/${effectiveBudget}`,
                         });
                     }
-                    console.log(`[hypermem-plugin] compact: NUCLEAR — session at ${currentTokenCount}/${effectiveBudget} tokens ` +
-                        `(${Math.round((currentTokenCount / effectiveBudget) * 100)}% full), ` +
+                    console.log(`[hypermem-plugin] compact: NUCLEAR — pressure=${s3NuclearPressure.pct}% source=${s3NuclearPressure.source} ` +
+                        `session at ${currentTokenCount}/${effectiveBudget} tokens, ` +
                         `deep-trimmed JSONL to ${nuclearDepth} messages, Redis ${tokensBefore}→${tokensAfter} tokens`);
                     return { ok: true, compacted: true, result: { tokensBefore, tokensAfter } };
                 }
@@ -2528,10 +2669,10 @@ ${replayRecovery.emittedText}`
                         postTokens: tokensAfter,
                         removed: historyTrimmed,
                         cacheInvalidated: true,
-                        reason: `over-budget tokensBefore=${tokensBefore}/${effectiveBudget}`,
+                        reason: `${s3CompactPressure.source}:${s3CompactPressure.pct}% over-budget tokensBefore=${tokensBefore}/${effectiveBudget}`,
                     });
                 }
-                console.log(`[hypermem-plugin] compact: trimmed ${tokensBefore} → ${tokensAfter} tokens (budget: ${effectiveBudget})`);
+                console.log(`[hypermem-plugin] compact: trimmed ${tokensBefore} → ${tokensAfter} tokens (budget: ${effectiveBudget}, pressure=${s3CompactPressure.pct}% source=${s3CompactPressure.source})`);
                 // Density-aware JSONL truncation: derive target depth from actual avg tokens/message
                 // rather than assuming a fixed 500 tokens/message. This prevents a large-message
                 // session (e.g. 145 msgs × 882 tok = 128k) from bypassing the 1.5x guard and
@@ -2608,8 +2749,54 @@ ${replayRecovery.emittedText}`
                         });
                     }
                 }
+                try {
+                    const lastAssistantMessage = [...newMessages].reverse().find(m => m.role === 'assistant');
+                    if (lastAssistantMessage) {
+                        const modelState = await hm.cache.getModelState(agentId, sk).catch(() => null);
+                        const promptCacheUsage = runtimeContext?.promptCache?.lastCallUsage;
+                        const outputTokens = resolveAssistantOutputTokenCount(lastAssistantMessage, runtimeContext) ?? 1;
+                        const inputTokens = typeof promptCacheUsage?.input === 'number'
+                            ? Math.floor(promptCacheUsage.input)
+                            : typeof runtimeContext?.currentTokenCount === 'number'
+                                ? Math.floor(runtimeContext.currentTokenCount)
+                                : null;
+                        const cacheReadTokens = typeof promptCacheUsage?.cacheRead === 'number'
+                            ? Math.floor(promptCacheUsage.cacheRead)
+                            : null;
+                        const modelId = typeof lastAssistantMessage.model === 'string'
+                            ? lastAssistantMessage.model
+                            : modelState?.modelId ?? modelState?.model ?? 'unknown';
+                        const provider = typeof lastAssistantMessage.provider === 'string'
+                            ? lastAssistantMessage.provider
+                            : modelState?.provider ?? 'unknown';
+                        const taskType = typeof runtimeContext?.taskType === 'string'
+                            ? runtimeContext.taskType ?? null
+                            : null;
+                        recordOutputMetrics(hm.dbManager.getLibraryDb(), {
+                            id: `turn-metric-${agentId}-${Date.now()}-${randomUUID()}`,
+                            timestamp: new Date().toISOString(),
+                            agent_id: agentId,
+                            session_key: sk,
+                            model_id: modelId,
+                            provider,
+                            fos_version: null,
+                            mod_version: null,
+                            mod_id: null,
+                            task_type: taskType,
+                            output_tokens: outputTokens,
+                            input_tokens: inputTokens,
+                            cache_read_tokens: cacheReadTokens,
+                            corrections_fired: [],
+                            latency_ms: null,
+                        });
+                    }
+                }
+                catch {
+                    // Non-fatal telemetry path
+                }
                 // P3.1: Topic detection on the inbound user message
                 // Non-fatal: topic detection never blocks afterTurn
+                let adaptiveTopicShiftConfidence;
                 try {
                     const inboundUserMsg = newMessages
                         .map(m => m)
@@ -2626,6 +2813,7 @@ ${replayRecovery.emittedText}`
                             const topicMap = new SessionTopicMap(db);
                             const activeTopic = topicMap.getActiveTopic(sk);
                             const signal = detectTopicShift(neutralUser, contextMessages, activeTopic?.id ?? null);
+                            adaptiveTopicShiftConfidence = signal.confidence;
                             if (signal.isNewTopic && signal.topicName) {
                                 const newTopicId = topicMap.createTopic(sk, signal.topicName);
                                 // New topic starts with count 1 (the message that triggered the shift)
@@ -2671,7 +2859,30 @@ ${replayRecovery.emittedText}`
                         const modelState = await hm.cache.getModelState(agentId, sk);
                         const gradientBudget = modelState?.tokenBudget;
                         const gradientDepth = modelState?.historyDepth;
-                        await hm.refreshRedisGradient(agentId, sk, gradientBudget, gradientDepth);
+                        const inboundUserMsg = newMessages
+                            .map(m => m)
+                            .find(m => m.role === 'user');
+                        const inboundUserText = inboundUserMsg
+                            ? stripMessageMetadata(extractTextFromInboundContent(inboundUserMsg.content))
+                            : '';
+                        const lifecyclePolicy = resolveAdaptiveLifecyclePolicy({
+                            usedTokens: estimateMessageArrayTokens(messages),
+                            effectiveBudget: gradientBudget,
+                            userTurnCount: messages.filter(m => m.role === 'user').length,
+                            explicitNewSession: /^\/new(?:\s|$)/i.test(inboundUserText.trim()),
+                            topicShiftConfidence: adaptiveTopicShiftConfidence,
+                        });
+                        lifecyclePolicyTelemetry({
+                            path: 'afterTurn.gradient',
+                            agentId,
+                            sessionKey: sk,
+                            band: lifecyclePolicy.band,
+                            pressurePct: lifecyclePolicy.pressurePct,
+                            topicShiftConfidence: adaptiveTopicShiftConfidence,
+                            trimSoftTarget: lifecyclePolicy.trimSoftTarget,
+                            reasons: lifecyclePolicy.reasons,
+                        });
+                        await hm.refreshRedisGradient(agentId, sk, gradientBudget, gradientDepth, lifecyclePolicy.trimSoftTarget);
                     }
                     catch (refreshErr) {
                         console.warn('[hypermem-plugin] afterTurn: refreshRedisGradient failed (non-fatal):', refreshErr.message);
@@ -2841,7 +3052,12 @@ ${replayRecovery.emittedText}`
          * subagentWarming config ('full' | 'light' | 'off').
          * Returns a rollback handle to clean up if spawn fails.
          */
-        async prepareSubagentSpawn({ parentSessionKey, childSessionKey }) {
+        async prepareSubagentSpawn(params) {
+            const { parentSessionKey, childSessionKey } = params;
+            const forkParams = params;
+            const contextMode = forkParams.contextMode;
+            const parentSessionId = forkParams.parentSessionId;
+            const childSessionId = forkParams.childSessionId;
             if (_subagentWarming === 'off') {
                 return undefined;
             }
@@ -2849,7 +3065,12 @@ ${replayRecovery.emittedText}`
                 const hm = await getHyperMem();
                 const parentAgentId = extractAgentId(parentSessionKey);
                 const childAgentId = extractAgentId(childSessionKey);
-                // Seed child with parent's active facts
+                const isForkedContext = contextMode === 'fork';
+                let parentHistoryMessages = 0;
+                let parentUserTurnCount = 0;
+                let parentPressureFraction;
+                // Seed child with parent's active facts. This preserves the historical
+                // slot for compatibility; facts still primarily come from L4 by agent id.
                 const facts = hm.getActiveFacts(parentAgentId, { limit: 50 });
                 if (facts && facts.length > 0) {
                     const factBlock = facts
@@ -2857,22 +3078,48 @@ ${replayRecovery.emittedText}`
                         .join('\n');
                     await hm.cache.setSlot(childAgentId, childSessionKey, 'parentFacts', factBlock);
                 }
-                // For 'full' warming, also seed recent history context
-                if (_subagentWarming === 'full') {
-                    const history = await hm.cache.getHistory(parentAgentId, parentSessionKey);
-                    if (history && history.length > 0) {
-                        const recentHistory = history.slice(-10);
-                        await hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', JSON.stringify(recentHistory));
+                const history = await hm.cache.getHistory(parentAgentId, parentSessionKey);
+                if (history && history.length > 0) {
+                    const maxSeededHistory = _subagentWarming === 'full' ? 25 : 12;
+                    const recentHistory = history.slice(-maxSeededHistory);
+                    parentHistoryMessages = recentHistory.length;
+                    parentUserTurnCount = recentHistory.filter(m => m.role === 'user').length;
+                    const parentTokens = estimateMessageArrayTokens(recentHistory);
+                    const parentModelState = await hm.cache.getModelState(parentAgentId, parentSessionKey).catch(() => null);
+                    const parentBudget = parentModelState?.tokenBudget && parentModelState.tokenBudget > 0
+                        ? parentModelState.tokenBudget
+                        : undefined;
+                    parentPressureFraction = parentBudget ? parentTokens / parentBudget : undefined;
+                    if (isForkedContext || _subagentWarming === 'full') {
+                        await hm.cache.replaceHistory(childAgentId, childSessionKey, recentHistory, maxSeededHistory);
+                        await hm.cache.invalidateWindow(childAgentId, childSessionKey).catch(() => { });
                     }
+                    await hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', JSON.stringify(recentHistory));
+                }
+                if (isForkedContext) {
+                    const forkedMeta = {
+                        enabled: true,
+                        parentSessionKey,
+                        parentSessionId,
+                        childSessionId,
+                        parentPressureFraction,
+                        parentUserTurnCount,
+                        parentHistoryMessages,
+                    };
+                    await hm.cache.setSlot(childAgentId, childSessionKey, FORKED_CONTEXT_META_SLOT, JSON.stringify(forkedMeta));
                 }
                 console.log(`[hypermem-plugin] prepareSubagentSpawn: seeded ${childSessionKey} ` +
-                    `from ${parentSessionKey} (warming=${_subagentWarming})`);
+                    `from ${parentSessionKey} (warming=${_subagentWarming}, contextMode=${contextMode ?? 'isolated'}, ` +
+                    `history=${parentHistoryMessages})`);
                 return {
                     async rollback() {
                         try {
                             const hm = await getHyperMem();
                             await hm.cache.setSlot(childAgentId, childSessionKey, 'parentFacts', '');
                             await hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', '');
+                            await hm.cache.setSlot(childAgentId, childSessionKey, FORKED_CONTEXT_META_SLOT, '');
+                            await hm.cache.replaceHistory(childAgentId, childSessionKey, [], 0);
+                            await hm.cache.invalidateWindow(childAgentId, childSessionKey).catch(() => { });
                         }
                         catch {
                             // Rollback is best-effort
@@ -2898,6 +3145,7 @@ ${replayRecovery.emittedText}`
                 await Promise.all([
                     hm.cache.setSlot(childAgentId, childSessionKey, 'parentFacts', ''),
                     hm.cache.setSlot(childAgentId, childSessionKey, 'parentHistory', ''),
+                    hm.cache.setSlot(childAgentId, childSessionKey, FORKED_CONTEXT_META_SLOT, ''),
                     hm.cache.setSlot(childAgentId, childSessionKey, 'assemblyContextBlock', ''),
                     hm.cache.setSlot(childAgentId, childSessionKey, 'assemblyContextAt', '0'),
                     hm.cache.invalidateWindow(childAgentId, childSessionKey).catch(() => { }),
@@ -3109,6 +3357,23 @@ const hypercompositorConfigSchema = z.object({
         timeout: z.number().int().positive().optional(),
         batchSize: z.number().int().positive().optional(),
     }).optional(),
+    /**
+     * Optional reranker config. When omitted or provider is 'none', the
+     * compositor runs with RRF-only ordering. See INSTALL.md → Reranker.
+     */
+    reranker: z.object({
+        provider: z.enum(['zeroentropy', 'openrouter', 'local', 'none']),
+        minCandidates: z.number().int().nonnegative().optional(),
+        maxDocuments: z.number().int().positive().optional(),
+        topK: z.number().int().positive().optional(),
+        timeoutMs: z.number().int().positive().optional(),
+        zeroEntropyApiKey: z.string().optional(),
+        zeroEntropyModel: z.string().optional(),
+        openrouterApiKey: z.string().optional(),
+        openrouterModel: z.string().optional(),
+        ollamaUrl: z.string().optional(),
+        ollamaModel: z.string().optional(),
+    }).optional(),
 });
 // ─── Plugin Entry ───────────────────────────────────────────────
 const engine = createHyperMemEngine();