@aexol/spectral 0.9.16 → 0.9.17

package/dist/memory/compaction.d.ts

@@ -1,7 +1,7 @@
 import { agentLoop } from "../sdk/agent-core/index.js";
 import { type Model } from "../sdk/ai/index.js";
 import type { MemoryReflection, ObservationRecord } from "./types.js";
-export declare const REFLECTOR_MAX_PASSES = 2;
+export declare const REFLECTOR_MAX_PASSES = 1;
 export declare const PRUNER_MAX_PASSES = 2;
 export declare function observationPoolTokens(observations: ObservationRecord[]): number;
 interface LlmArgs {

package/dist/memory/compaction.js

@@ -8,8 +8,8 @@ import { buildPrunerPassGuidance, buildReflectorPassGuidance, CONTEXT_USAGE_INST
 import { truncateRecordContent } from "./serialize.js";
 import { estimateStringTokens } from "./tokens.js";
 import { reflectionContent, reflectionToPromptLine } from "./types.js";
-export const REFLECTOR_MAX_PASSES = 2;
-export const PRUNER_MAX_PASSES = 2;
+export const REFLECTOR_MAX_PASSES = 1;
+export const PRUNER_MAX_PASSES = 2; // Kept for compatibility; deterministic pruner replaces this
 const PRUNER_TARGET_RATIO = 0.8;
 export function observationPoolTokens(observations) {
     return estimateStringTokens(observationsToPromptLines(observations).join("\n"));
@@ -293,7 +293,7 @@ function reflectorPassContext(pass) {
     return {
         pass,
         maxPasses: REFLECTOR_MAX_PASSES,
-        minSupportingObservationIds: pass === 1 ? 2 : 1,
+        minSupportingObservationIds: REFLECTOR_MAX_PASSES === 1 ? 1 : (pass === 1 ? 2 : 1),
     };
 }
 function reflectionContentKey(reflection) {

package/dist/memory/deterministic-pruner.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Deterministic Pruner — replaces the 2-pass LLM-based pruner with a
+ * sorting algorithm that drops observations based on coverage, relevance,
+ * and age.
+ *
+ * The algorithm mirrors the LLM pruner's strategy:
+ *   1. Coverage-tagged observations (reinforced by reflections) drop first
+ *   2. Within same coverage: low > medium > high relevance
+ *   3. Within same relevance: oldest first (age-gradient rule)
+ *   4. Protected observations NEVER drop (critical, user assertions, completions)
+ *
+ * This eliminates ~2 LLM calls per compaction while producing equivalent results.
+ */
+import type { MemoryReflection, ObservationRecord } from "./types.js";
+export type CoverageTag = "reinforced" | "cited" | "uncited";
+export interface TaggedObservation {
+    observation: ObservationRecord;
+    coverage: CoverageTag;
+    /** Number of reflections that cite this observation */
+    citationCount: number;
+    /** True if this observation should never be dropped */
+    protected: boolean;
+    /** Reason for protection (for debugging) */
+    protectedReason?: string;
+}
+/**
+ * Compute coverage tags for all observations based on reflection citations.
+ * - reinforced: ≥4 reflections cite this observation
+ * - cited: 1-3 reflections cite this observation
+ * - uncited: no reflection cites this observation
+ */
+export declare function computeCoverageTags(observations: ObservationRecord[], reflections: MemoryReflection[]): Map<string, CoverageTag>;
+/**
+ * Tag observations with protection status.
+ */
+export declare function tagProtectedObservations(observations: ObservationRecord[]): Map<string, {
+    protected: boolean;
+    reason?: string;
+}>;
+export interface PrunerResult {
+    /** Kept observations */
+    observations: ObservationRecord[];
+    /** IDs of dropped observations */
+    droppedIds: string[];
+    /** Whether any protected observations were at risk of being dropped */
+    fellBack: boolean;
+    /** Tokens before pruning */
+    tokensBefore: number;
+    /** Tokens after pruning */
+    tokensAfter: number;
+}
+/**
+ * Deterministically prune an observation pool to fit within a token budget.
+ *
+ * Algorithm:
+ *   1. Compute coverage tags from reflection citations
+ *   2. Detect protected observations (critical, assertions, completions, errors, unique IDs)
+ *   3. Sort by droppability (reinforced+low+oldest first)
+ *   4. Drop from the sorted list until pool ≤ targetTokens
+ *   5. Never drop protected observations
+ *
+ * Target is 80% of the budget to leave breathing room for the summary text.
+ */
+export declare function deterministicPrune(observations: ObservationRecord[], reflections: MemoryReflection[], budgetTokens: number): PrunerResult;
+//# sourceMappingURL=deterministic-pruner.d.ts.map

package/dist/memory/deterministic-pruner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deterministic-pruner.d.ts","sourceRoot":"","sources":["../../src/memory/deterministic-pruner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAStE,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IACjC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,SAAS,EAAE,OAAO,CAAC;IACnB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,YAAY,EAAE,iBAAiB,EAAE,EACjC,WAAW,EAAE,gBAAgB,EAAE,GAC7B,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CA2B1B;AAuHD;;GAEG;AACH,wBAAgB,wBAAwB,CACvC,YAAY,EAAE,iBAAiB,EAAE,GAC/B,GAAG,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA0CtD;AAoDD,MAAM,WAAW,YAAY;IAC5B,wBAAwB;IACxB,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,kCAAkC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;IAClB,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CACjC,YAAY,EAAE,iBAAiB,EAAE,EACjC,WAAW,EAAE,gBAAgB,EAAE,EAC/B,YAAY,EAAE,MAAM,GAClB,YAAY,CA8Fd"}

package/dist/memory/deterministic-pruner.js

@@ -0,0 +1,333 @@
+/**
+ * Deterministic Pruner — replaces the 2-pass LLM-based pruner with a
+ * sorting algorithm that drops observations based on coverage, relevance,
+ * and age.
+ *
+ * The algorithm mirrors the LLM pruner's strategy:
+ *   1. Coverage-tagged observations (reinforced by reflections) drop first
+ *   2. Within same coverage: low > medium > high relevance
+ *   3. Within same relevance: oldest first (age-gradient rule)
+ *   4. Protected observations NEVER drop (critical, user assertions, completions)
+ *
+ * This eliminates ~2 LLM calls per compaction while producing equivalent results.
+ */
+import { estimateStringTokens } from "./tokens.js";
+import { debugLog, isDebugLogEnabled } from "./debug-log.js";
+/**
+ * Compute coverage tags for all observations based on reflection citations.
+ * - reinforced: ≥4 reflections cite this observation
+ * - cited: 1-3 reflections cite this observation
+ * - uncited: no reflection cites this observation
+ */
+export function computeCoverageTags(observations, reflections) {
+    const citationCounts = new Map();
+    // Initialize counts
+    for (const obs of observations) {
+        citationCounts.set(obs.id, 0);
+    }
+    // Count citations from reflections
+    for (const reflection of reflections) {
+        if (typeof reflection === "string" || reflection.legacy === true)
+            continue;
+        for (const obsId of reflection.supportingObservationIds) {
+            const count = citationCounts.get(obsId);
+            if (count !== undefined) {
+                citationCounts.set(obsId, count + 1);
+            }
+        }
+    }
+    // Compute tags
+    const tags = new Map();
+    for (const obs of observations) {
+        const count = citationCounts.get(obs.id) ?? 0;
+        tags.set(obs.id, count >= 4 ? "reinforced" : count >= 1 ? "cited" : "uncited");
+    }
+    return tags;
+}
+// ============================================================================
+// Protection Detection
+// ============================================================================
+/** Patterns indicating a user assertion (identity, preference, constraint). */
+const USER_ASSERTION_PATTERNS = [
+    /\buser\s+(stated|said|mentioned|confirmed|reported|asserted|told|specified)\b/i,
+    /\buser\s+(prefers|prefer|wants|needs|requires|insists|demands)\b/i,
+    /\buser\s+(is|has|was|will|can|does)\b/i,
+    /\buser\s+(decided|chose|picked|selected|opted)\b/i,
+];
+/** Patterns indicating a concrete completion that should not be redone. */
+const COMPLETION_PATTERNS = [
+    /\bcompleted[:\s]/i,
+    /\bresolved[:\s]/i,
+    /\bconfirmed working\b/i,
+    /\bfinished[:\s]/i,
+    /\bimplemented[:\s]/i,
+    /\bmerged[:\s]/i,
+    /\bdeployed[:\s]/i,
+    /\bfix(ed)?[:\s]/i,
+];
+/** Patterns indicating verbatim error messages. */
+const ERROR_PATTERNS = [
+    /\bTS\d{4,5}\b/, // TypeScript error codes
+    /\bE[A-Z]+\d+\b/, // Generic error codes
+    /\bError:\s/i,
+    /\bfailed[:\s]/i,
+    /\bpanic[:\s]/i,
+    /\bstack trace\b/i,
+    /\bat\s+\S+:\d+:\d+\b/, // Stack trace lines
+    /\bCannot\s+(find|read|write|open|access|parse|resolve)\b/i,
+    /\bnot\s+(found|supported|allowed|permitted|valid)\b/i,
+];
+/**
+ * Detect if an observation content contains a user assertion.
+ */
+function isUserAssertion(content) {
+    return USER_ASSERTION_PATTERNS.some((p) => p.test(content));
+}
+/**
+ * Detect if an observation content marks a concrete completion.
+ */
+function isCompletion(content) {
+    return COMPLETION_PATTERNS.some((p) => p.test(content));
+}
+/**
+ * Detect if an observation content contains a verbatim error.
+ */
+function isVerbatimError(content) {
+    return ERROR_PATTERNS.some((p) => p.test(content));
+}
+/**
+ * Detect if an observation contains unique identifiers that appear nowhere else.
+ * Checks for file paths, package names, commit SHAs, ticket IDs, error codes.
+ */
+function hasUniqueIdentifiers(observation, allObservations) {
+    // Extract potential identifiers
+    const identifiers = extractIdentifiers(observation.content);
+    if (identifiers.length === 0)
+        return false;
+    // Check if ANY of these identifiers appear in other observations
+    for (const id of identifiers) {
+        let foundElsewhere = false;
+        for (const other of allObservations) {
+            if (other.id === observation.id)
+                continue;
+            if (other.content.includes(id)) {
+                foundElsewhere = true;
+                break;
+            }
+        }
+        if (!foundElsewhere)
+            return true; // This identifier is unique to this observation
+    }
+    return false;
+}
+/**
+ * Extract potential identifiers from observation content.
+ * Looks for: file paths, package names, commit SHAs, ticket IDs, error codes.
+ */
+function extractIdentifiers(content) {
+    const ids = [];
+    // File paths: /path/to/file.ext or relative/path/file.ext or src/file.ts
+    const pathMatches = content.match(/\b[\w./-]+\.[\w]{1,10}\b/g);
+    if (pathMatches)
+        ids.push(...pathMatches);
+    // Package names: @scope/name or package-name
+    const pkgMatches = content.match(/@[\w-]+\/[\w-]+|\b[\w-]+-[\w-]+(?:\/[\w-]+)*\b/g);
+    if (pkgMatches)
+        ids.push(...pkgMatches);
+    // Commit SHAs: 7-40 hex chars
+    const shaMatches = content.match(/\b[a-f0-9]{7,40}\b/gi);
+    if (shaMatches)
+        ids.push(...shaMatches);
+    // Ticket IDs: PROJ-123 or #1234
+    const ticketMatches = content.match(/\b[A-Z]{2,}-\d+\b|#\d{3,}\b/g);
+    if (ticketMatches)
+        ids.push(...ticketMatches);
+    // Error codes: TS2322, ENOENT, etc.
+    const errorCodeMatches = content.match(/\b(?:TS|E[A-Z])\d{2,}\b/g);
+    if (errorCodeMatches)
+        ids.push(...errorCodeMatches);
+    // Deduplicate and filter very short/generic identifiers
+    return [...new Set(ids)].filter((id) => id.length > 4 && !/^[\d.]+$/.test(id));
+}
+/**
+ * Tag observations with protection status.
+ */
+export function tagProtectedObservations(observations) {
+    const protected_ = new Map();
+    for (const obs of observations) {
+        // Critical relevance is always protected
+        if (obs.relevance === "critical") {
+            protected_.set(obs.id, { protected: true, reason: "critical relevance" });
+            continue;
+        }
+        // User assertions about identity/preferences/constraints
+        if (isUserAssertion(obs.content)) {
+            protected_.set(obs.id, { protected: true, reason: "user assertion" });
+            continue;
+        }
+        // Concrete completions
+        if (isCompletion(obs.content)) {
+            protected_.set(obs.id, { protected: true, reason: "completion marker" });
+            continue;
+        }
+        // Verbatim errors
+        if (isVerbatimError(obs.content)) {
+            protected_.set(obs.id, { protected: true, reason: "verbatim error" });
+            continue;
+        }
+        // Unique identifiers (will be checked below)
+        protected_.set(obs.id, { protected: false });
+    }
+    // Second pass: check for unique identifiers across all observations
+    for (const obs of observations) {
+        const status = protected_.get(obs.id);
+        if (status?.protected)
+            continue; // Already protected
+        if (hasUniqueIdentifiers(obs, observations)) {
+            protected_.set(obs.id, { protected: true, reason: "unique identifiers" });
+        }
+    }
+    return protected_;
+}
+// ============================================================================
+// Sorting & Pruning
+// ============================================================================
+const COVERAGE_PRIORITY = {
+    reinforced: 0, // Drop first
+    cited: 1,
+    uncited: 2, // Drop last (among non-protected)
+};
+const RELEVANCE_PRIORITY = {
+    low: 0,
+    medium: 1,
+    high: 2,
+    critical: 3,
+};
+/**
+ * Sort observations for pruning: most droppable first, protected last.
+ *
+ * Priority order (ascending = drop first):
+ *   1. Coverage: reinforced → cited → uncited
+ *   2. Relevance: low → medium → high → critical
+ *   3. Age: oldest → newest
+ *   4. Protected: always last
+ */
+function sortForPruning(tagged) {
+    return [...tagged].sort((a, b) => {
+        // Protected always last
+        if (a.protected !== b.protected) {
+            return a.protected ? 1 : -1;
+        }
+        // Coverage priority
+        const covA = COVERAGE_PRIORITY[a.coverage];
+        const covB = COVERAGE_PRIORITY[b.coverage];
+        if (covA !== covB)
+            return covA - covB;
+        // Relevance priority
+        const relA = RELEVANCE_PRIORITY[a.observation.relevance] ?? 1;
+        const relB = RELEVANCE_PRIORITY[b.observation.relevance] ?? 1;
+        if (relA !== relB)
+            return relA - relB;
+        // Age: oldest first (lexicographic timestamp comparison)
+        const timeA = a.observation.timestamp ?? "";
+        const timeB = b.observation.timestamp ?? "";
+        return timeA.localeCompare(timeB);
+    });
+}
+/**
+ * Deterministically prune an observation pool to fit within a token budget.
+ *
+ * Algorithm:
+ *   1. Compute coverage tags from reflection citations
+ *   2. Detect protected observations (critical, assertions, completions, errors, unique IDs)
+ *   3. Sort by droppability (reinforced+low+oldest first)
+ *   4. Drop from the sorted list until pool ≤ targetTokens
+ *   5. Never drop protected observations
+ *
+ * Target is 80% of the budget to leave breathing room for the summary text.
+ */
+export function deterministicPrune(observations, reflections, budgetTokens) {
+    if (observations.length === 0) {
+        return {
+            observations: [],
+            droppedIds: [],
+            fellBack: false,
+            tokensBefore: 0,
+            tokensAfter: 0,
+        };
+    }
+    const targetTokens = Math.max(1, Math.floor(budgetTokens * 0.8));
+    const coverageTags = computeCoverageTags(observations, reflections);
+    const protectionStatus = tagProtectedObservations(observations);
+    // Build tagged observations
+    const tagged = observations.map((obs) => {
+        const coverage = coverageTags.get(obs.id) ?? "uncited";
+        const citationCount = [...reflections]
+            .filter((r) => typeof r !== "string" && !r.legacy)
+            .reduce((sum, r) => {
+            if (typeof r === "string")
+                return sum;
+            return sum + (r.supportingObservationIds.includes(obs.id) ? 1 : 0);
+        }, 0);
+        const prot = protectionStatus.get(obs.id);
+        return {
+            observation: obs,
+            coverage,
+            citationCount,
+            protected: prot?.protected ?? false,
+            protectedReason: prot?.reason,
+        };
+    });
+    const tokensBefore = observations.reduce((sum, o) => sum + estimateStringTokens(o.content), 0);
+    // If already under budget, no pruning needed
+    if (tokensBefore <= targetTokens) {
+        debugLog("deterministic_pruner.under_target", {
+            tokensBefore,
+            targetTokens,
+            observationCount: observations.length,
+        });
+        return {
+            observations,
+            droppedIds: [],
+            fellBack: false,
+            tokensBefore,
+            tokensAfter: tokensBefore,
+        };
+    }
+    // Sort for pruning
+    const sorted = sortForPruning(tagged);
+    // Drop from the front until budget is met
+    const dropped = new Set();
+    let currentTokens = tokensBefore;
+    for (const item of sorted) {
+        // Never drop protected observations
+        if (item.protected)
+            continue;
+        // Stop if we're under budget
+        if (currentTokens <= targetTokens)
+            break;
+        dropped.add(item.observation.id);
+        currentTokens -= estimateStringTokens(item.observation.content);
+    }
+    // Check if we couldn't reach the budget because too many observations are protected
+    const fellBack = currentTokens > targetTokens && dropped.size < sorted.filter((s) => !s.protected).length;
+    const kept = observations.filter((o) => !dropped.has(o.id));
+    const droppedIds = Array.from(dropped);
+    debugLog("deterministic_pruner.result", {
+        tokensBefore,
+        tokensAfter: currentTokens,
+        targetTokens,
+        dropped: droppedIds.length,
+        remaining: kept.length,
+        protectedCount: sorted.filter((s) => s.protected).length,
+        fellBack,
+        droppedIds: isDebugLogEnabled() ? droppedIds : undefined,
+    });
+    return {
+        observations: kept,
+        droppedIds,
+        fellBack,
+        tokensBefore,
+        tokensAfter: currentTokens,
+    };
+}

package/dist/memory/hooks/compaction-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA+C,MAAM,iCAAiC,CAAC;AAuBjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAmE7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA+XhF"}
+{"version":3,"file":"compaction-hook.d.ts","sourceRoot":"","sources":["../../../src/memory/hooks/compaction-hook.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAA+C,MAAM,iCAAiC,CAAC;AAoBjH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAgE7C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CA0bhF"}

package/dist/memory/hooks/compaction-hook.js

@@ -3,11 +3,12 @@ import { resolveTurnLimits } from "../config.js";
 import { getProjectObsStore } from "../project-observations-store.js";
 import { relayProjectObservations } from "../inter-agent-relay.js";
 import { collectObservationsByCoverage, findLastCompactionIndex, gapRawEntries, getMemoryState, } from "../branch.js";
-import { coverageTagCounts, migrateLegacyReflections, observationPoolTokens, renderSummary, runPruner, runReflector, } from "../compaction.js";
-import { observationsToPromptLines, runObserver } from "../observer.js";
+import { coverageTagCounts, migrateLegacyReflections, observationPoolTokens, renderSummary, runReflector, } from "../compaction.js";
 import { serializeSourceAddressedBranchEntries } from "../serialize.js";
 import { estimateStringTokens } from "../tokens.js";
-import { OBSERVATION_CUSTOM_TYPE, reflectionToPromptLine, } from "../types.js";
+import { OBSERVATION_CUSTOM_TYPE, } from "../types.js";
+import { deterministicPrune } from "../deterministic-pruner.js";
+import { generateUnifiedCompaction } from "../unified-compaction.js";
 function plural(count, singular, pluralForm = `${singular}s`) {
     return `${count.toLocaleString()} ${count === 1 ? singular : pluralForm}`;
 }
@@ -18,9 +19,6 @@ function formatReflectorStats(stats) {
     const failed = stats.failedPass === undefined ? "" : `, failed pass ${stats.failedPass}`;
     return `reflector ${plural(stats.toolCalls, "tool call")}, +${stats.added.toLocaleString()} added, ${stats.merged.toLocaleString()} merged, ${stats.promoted.toLocaleString()} promoted, ${stats.duplicates.toLocaleString()} duplicate/no-op, ${stats.unsupported.toLocaleString()} unsupported${failed}`;
 }
-function formatPrunerStats(result) {
-    return `pruner dropped ${plural(result.droppedIds.length, "observation")} in ${plural(result.passes.length, "pass", "passes")}, stop: ${result.stopReason}`;
-}
 function emitProgressLine(emitProgress, line) {
     emitProgress?.(`${line}\n`);
 }
@@ -61,8 +59,6 @@ function emitAgentLoopProgress(emitProgress, phase, event) {
 export function registerCompactionHook(ext, runtime) {
     ext.on("session_before_compact", async (event, ctx) => {
         if (runtime.compactHookInFlight) {
-            // Expected race: another compaction process reached the hook first.
-            // Let the in-flight compaction continue; this is not a user-facing error.
             debugLog("compaction.skip_duplicate", { reason: "hook already in flight" });
             return { cancel: true };
         }
@@ -72,11 +68,9 @@ export function registerCompactionHook(ext, runtime) {
             const runId = `compaction-${Date.now().toString(36)}-${Math.random().toString(16).slice(2, 8)}`;
             return await withDebugLogContext({ enabled: runtime.config.debugLog === true, cwd: ctx.cwd, runId }, async () => {
                 const { preparation, branchEntries, signal } = event;
-                const { firstKeptEntryId, tokensBefore } = preparation;
+                const { firstKeptEntryId, tokensBefore, messagesToSummarize, settings: compactSettings } = preparation;
                 const emitProgress = event.emitProgress;
                 emitProgressLine(emitProgress, `Observational memory compaction started on ~${tokensBefore.toLocaleString()} tokens.`);
-                // Capture ctx properties synchronously — after multiple awaits below,
-                // the extension ctx may become stale (e.g. after session replacement/reload).
                 const hasUI = ctx.hasUI;
                 const ui = ctx.ui;
                 const turnLimits = resolveTurnLimits(runtime.config);
@@ -86,7 +80,7 @@ export function registerCompactionHook(ext, runtime) {
                     branchEntryCount: branchEntries.length,
                     reflectionThresholdTokens: runtime.config.reflectionThresholdTokens,
                     turnLimits,
-                    legacyCompactionMaxToolCalls: runtime.config.compactionMaxToolCalls,
+                    messagesToSummarize: messagesToSummarize?.length ?? 0,
                 });
                 emitProgressLine(emitProgress, "Resolving memory model…");
                 const resolved = await runtime.resolveModel(ctx);
@@ -105,9 +99,7 @@ export function registerCompactionHook(ext, runtime) {
                     try {
                         await runtime.observerPromise;
                     }
-                    catch { /* already notified via launchObserverTask */ }
-                    // In-flight observer may have appended a new observation entry during the await;
-                    // refresh from sessionManager so gap computation and coverage collection see it
+                    catch { /* already notified */ }
                     entries = ctx.sessionManager.getBranch();
                 }
                 const memoryState = getMemoryState(entries);
@@ -117,88 +109,84 @@ export function registerCompactionHook(ext, runtime) {
                     reflections: memoryState.reflections.length,
                 });
                 emitProgressLine(emitProgress, `Loaded memory state: ${memoryState.committedObs.length} committed observations, ${memoryState.pendingObs.length} pending observations, ${memoryState.reflections.length} reflections.`);
+                // ================================================================
+                // UNIFIED COMPACTION: replaces core generateSummary() + sync
+                // catch-up observer with a single LLM call.
+                // ================================================================
                 let gapObservationData = null;
+                let unifiedNarrativeSummary;
+                let unifiedObservations = [];
                 const gap = gapRawEntries(entries, firstKeptEntryId);
-                if (gap.length > 0) {
-                    const { text: gapChunk, sourceEntryIds } = serializeSourceAddressedBranchEntries(gap);
-                    if (gapChunk.trim() && sourceEntryIds.length > 0) {
+                const gapChunk = gap.length > 0
+                    ? serializeSourceAddressedBranchEntries(gap)
+                    : { text: "", sourceEntryIds: [] };
+                const hasGapContent = gapChunk.text.trim() && gapChunk.sourceEntryIds.length > 0;
+                // Always run unified compaction — it replaces both the core narrative
+                // summary and, when gap exists, the sync catch-up observer.
+                emitProgressLine(emitProgress, "Running unified compaction (narrative + observations)…");
+                debugLog("compaction.unified.start", {
+                    messagesToSummarize: messagesToSummarize.length,
+                    hasGapContent,
+                    gapEntryCount: gap.length,
+                });
+                try {
+                    const unifiedResult = await generateUnifiedCompaction({
+                        messagesToSummarize,
+                        gapChunk: hasGapContent ? gapChunk.text : undefined,
+                        gapSourceEntryIds: hasGapContent ? gapChunk.sourceEntryIds : undefined,
+                        model: resolved.model,
+                        apiKey: resolved.apiKey,
+                        headers: resolved.headers,
+                        signal,
+                        previousSummary: preparation.previousSummary,
+                        customInstructions: event.customInstructions,
+                        thinkingLevel: undefined, // Use model default
+                        reserveTokens: compactSettings.reserveTokens,
+                    });
+                    unifiedNarrativeSummary = unifiedResult.narrativeSummary;
+                    unifiedObservations = unifiedResult.observations;
+                    // If gap entries produced observations, record them as an
+                    // observation entry so recall can resolve source provenance.
+                    if (hasGapContent && unifiedObservations.length > 0) {
                         const gapFromId = gap[0].id;
                         const gapUpToId = gap[gap.length - 1].id;
-                        const priorObservationLines = observationsToPromptLines([
-                            ...memoryState.committedObs,
-                            ...memoryState.pendingObs,
-                        ]);
-                        const gapTokenEstimate = estimateStringTokens(gapChunk);
-                        debugLog("compaction.sync_catchup.start", {
-                            gapEntryCount: gap.length,
-                            sourceEntryIds,
-                            gapFromId,
-                            gapUpToId,
-                            tokenEstimate: gapTokenEstimate,
-                        });
-                        if (hasUI)
-                            ui?.notify(`Observational memory: sync catch-up observer running on ~${gapTokenEstimate.toLocaleString()}-token gap`, "info");
-                        runtime.observerInFlight = true;
-                        const gapCall = runObserver({
-                            model: resolved.model,
-                            apiKey: resolved.apiKey,
-                            headers: resolved.headers,
-                            priorReflections: memoryState.reflections.map(reflectionToPromptLine),
-                            priorObservations: priorObservationLines,
-                            chunk: gapChunk,
-                            allowedSourceEntryIds: sourceEntryIds,
-                            signal,
-                            onEvent: (agentEvent) => emitAgentLoopProgress(emitProgress, "observer", agentEvent),
-                            maxTurns: turnLimits.observerMaxTurnsPerRun,
-                        });
-                        const gapPromise = gapCall.then(() => undefined, () => undefined);
-                        runtime.observerPromise = gapPromise;
-                        try {
-                            const records = await gapCall;
-                            if (records && records.length > 0) {
-                                const observationTokens = records.reduce((sum, r) => sum + estimateStringTokens(r.content), 0);
-                                gapObservationData = {
-                                    records,
-                                    coversFromId: gapFromId,
-                                    coversUpToId: gapUpToId,
-                                    tokenCount: observationTokens,
-                                };
-                                debugLog("compaction.sync_catchup.records", {
-                                    count: records.length,
-                                    observationTokens,
-                                    coversFromId: gapFromId,
-                                    coversUpToId: gapUpToId,
-                                    records,
-                                });
-                                ext.appendEntry(OBSERVATION_CUSTOM_TYPE, gapObservationData);
-                                emitProgressLine(emitProgress, `Sync catch-up recorded ${records.length} observation${records.length === 1 ? "" : "s"} (~${observationTokens.toLocaleString()} tokens).`);
-                                if (hasUI && ui)
-                                    ui.notify(`Observational memory: sync catch-up recorded ${records.length} observation${records.length === 1 ? "" : "s"} (~${observationTokens.toLocaleString()} tokens)`, "info");
-                            }
-                            else if (hasUI && ui) {
-                                debugLog("compaction.sync_catchup.empty", { gapEntryCount: gap.length });
-                                ui.notify("Observational memory: sync catch-up observer returned empty — proceeding with compaction", "warning");
-                            }
-                        }
-                        catch (error) {
-                            const msg = error instanceof Error ? error.message : String(error);
-                            debugLog("compaction.sync_catchup.error", { gapEntryCount: gap.length, errorMessage: msg });
-                            if (hasUI && ui)
-                                ui.notify(`Observational memory: sync catch-up observer failed: ${msg}. Cancelling compaction — ${gap.length} unobserved raw entries would be pruned without coverage. Try /compact again.`, "warning");
-                            return { cancel: true };
-                        }
-                        finally {
-                            runtime.observerInFlight = false;
-                            if (runtime.observerPromise === gapPromise)
-                                runtime.observerPromise = null;
-                        }
+                        const observationTokens = unifiedObservations.reduce((sum, r) => sum + estimateStringTokens(r.content), 0);
+                        gapObservationData = {
+                            records: unifiedObservations,
+                            coversFromId: gapFromId,
+                            coversUpToId: gapUpToId,
+                            tokenCount: observationTokens,
+                        };
+                        ext.appendEntry(OBSERVATION_CUSTOM_TYPE, gapObservationData);
+                        emitProgressLine(emitProgress, `Unified compaction recorded ${unifiedObservations.length} observation${unifiedObservations.length === 1 ? "" : "s"} from gap (~${observationTokens.toLocaleString()} tokens).`);
                     }
+                    debugLog("compaction.unified.result", {
+                        narrativeLength: unifiedNarrativeSummary?.length ?? 0,
+                        observationCount: unifiedObservations.length,
+                    });
+                    if (hasUI && ui) {
+                        ui.notify(`Observational memory: unified compaction produced ${unifiedObservations.length} observation${unifiedObservations.length === 1 ? "" : "s"} + narrative summary`, "info");
+                    }
+                }
+                catch (error) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    debugLog("compaction.unified.error", { errorMessage: msg });
+                    if (hasUI && ui)
+                        ui.notify(`Observational memory: unified compaction failed: ${msg}. Cancelling compaction.`, "warning");
+                    return { cancel: true };
                 }
+                // ================================================================
+                // DELTA OBSERVATIONS: collect observer-trigger observations that
+                // fall within this compaction window (from prior FKI to new FKI).
+                // ================================================================
                 const priorCompactionIdx = findLastCompactionIndex(entries);
                 const priorFirstKeptEntryId = priorCompactionIdx >= 0 ? entries[priorCompactionIdx].firstKeptEntryId : undefined;
                 const deltaObservationData = collectObservationsByCoverage(entries, priorFirstKeptEntryId, firstKeptEntryId);
-                if (gapObservationData)
-                    deltaObservationData.push(gapObservationData);
+                // Gap observations were already appended via ext.appendEntry above,
+                // so collectObservationsByCoverage will pick them up. But to avoid
+                // double-counting (the unified observations are also in our local set),
+                // we build the working set from committed + delta, then merge unified
+                // observations (deduplicated by content hash).
                 const deltaObservationRecords = deltaObservationData.reduce((sum, data) => sum + data.records.length, 0);
                 debugLog("compaction.delta", {
                     priorFirstKeptEntryId,
@@ -208,10 +196,10 @@ export function registerCompactionHook(ext, runtime) {
                     gapObservationRecords: gapObservationData?.records.length ?? 0,
                 });
                 emitProgressLine(emitProgress, `Compaction delta contains ${deltaObservationRecords} observation${deltaObservationRecords === 1 ? "" : "s"}.`);
-                if (deltaObservationData.length === 0) {
-                    // No new observations since last compaction. If we have existing memory,
-                    // carry it forward in a no-op compaction so it survives spectral's compaction.
-                    // If there is truly nothing (no prior memory either), cancel.
+                // ================================================================
+                // NO-DELTA CASE: carry forward existing memory.
+                // ================================================================
+                if (deltaObservationData.length === 0 && unifiedObservations.length === 0) {
                     if (memoryState.committedObs.length === 0 && memoryState.reflections.length === 0) {
                         debugLog("compaction.no_delta_cancel", {
                             committedObservations: memoryState.committedObs.length,
@@ -223,7 +211,6 @@ export function registerCompactionHook(ext, runtime) {
                         }
                         return { cancel: true };
                     }
-                    // Carry forward existing memory without running reflector/pruner
                     emitProgressLine(emitProgress, "No new observations; carrying forward existing memory.");
                     const workingReflections = migrateLegacyReflections(memoryState.reflections);
                     debugLog("compaction.no_delta_carry_forward", {
@@ -239,7 +226,6 @@ export function registerCompactionHook(ext, runtime) {
                     };
                     if (hasUI)
                         ui?.notify(`Observational memory: no new observations — carrying forward ${memoryState.committedObs.length} observation${memoryState.committedObs.length === 1 ? "" : "s"}, ${workingReflections.length} reflection${workingReflections.length === 1 ? "" : "s"}`, "info");
-                    // Promote reflections as project observations (cross-session durable memory).
                     persistProjectObservations(ctx, workingReflections);
                     return {
                         compaction: {
@@ -250,32 +236,61 @@ export function registerCompactionHook(ext, runtime) {
                         },
                     };
                 }
+                // ================================================================
+                // BUILD WORKING SET: committed + delta (from observer triggers) +
+                // unified observations (from this compaction).
+                // Deduplicate by content hash.
+                // ================================================================
+                const seenObsIds = new Set();
+                const workingObservations = [];
+                // Add committed observations first (most stable)
+                for (const obs of memoryState.committedObs) {
+                    if (!seenObsIds.has(obs.id)) {
+                        seenObsIds.add(obs.id);
+                        workingObservations.push(obs);
+                    }
+                }
+                // Add delta observations (from observer triggers between compactions)
+                for (const data of deltaObservationData) {
+                    for (const obs of data.records) {
+                        if (!seenObsIds.has(obs.id)) {
+                            seenObsIds.add(obs.id);
+                            workingObservations.push(obs);
+                        }
+                    }
+                }
+                // Add unified observations (from this compaction's LLM call)
+                for (const obs of unifiedObservations) {
+                    if (!seenObsIds.has(obs.id)) {
+                        seenObsIds.add(obs.id);
+                        workingObservations.push(obs);
+                    }
+                }
                 const workingReflections = migrateLegacyReflections(memoryState.reflections);
-                const workingObservations = [
-                    ...memoryState.committedObs,
-                    ...deltaObservationData.flatMap((d) => d.records),
-                ];
                 const observationTokens = observationPoolTokens(workingObservations);
                 emitProgressLine(emitProgress, `Working set: ${workingObservations.length} observations, ${workingReflections.length} reflections, ~${observationTokens.toLocaleString()} observation tokens.`);
-                debugLog("compaction.reflect_prune.gate", {
+                debugLog("compaction.working_set", {
+                    observations: workingObservations.length,
+                    reflections: workingReflections.length,
                     observationTokens,
-                    reflectionThresholdTokens: runtime.config.reflectionThresholdTokens,
-                    willRun: observationTokens >= runtime.config.reflectionThresholdTokens,
-                    workingObservations: workingObservations.length,
-                    workingReflections: workingReflections.length,
                 });
+                // ================================================================
+                // REFLECTOR (1 pass): crystallize durable reflections from
+                // the observation pool. Preserves quality-critical iteration
+                // via agentLoop with record_reflections tool.
+                // ================================================================
                 let finalReflections = workingReflections;
                 let finalObservations = workingObservations;
                 if (observationTokens >= runtime.config.reflectionThresholdTokens) {
                     try {
-                        debugLog("compaction.reflect_prune.start", {
+                        debugLog("compaction.reflect.start", {
                             workingObservations: workingObservations.length,
                             workingReflections: workingReflections.length,
                             observationTokens,
                         });
                         if (hasUI)
-                            ui?.notify("Observational memory: running reflector + pruner...", "info");
-                        emitProgressLine(emitProgress, "Running reflector + pruner…");
+                            ui?.notify("Observational memory: running reflector (1 pass)...", "info");
+                        emitProgressLine(emitProgress, "Running reflector (1 pass)…");
                         const coverageBefore = coverageTagCounts(workingReflections, workingObservations);
                         const reflectorResult = await runReflector({
                             model: resolved.model,
@@ -294,39 +309,49 @@ export function registerCompactionHook(ext, runtime) {
                             beforeReflections: workingReflections.length,
                             afterReflections: finalReflections.length,
                         });
-                        const prunerResult = await runPruner({
-                            model: resolved.model,
-                            apiKey: resolved.apiKey,
-                            headers: resolved.headers,
-                            signal,
-                            onEvent: (agentEvent) => emitAgentLoopProgress(emitProgress, "pruner", agentEvent),
-                            maxTurns: turnLimits.prunerMaxTurnsPerPass,
-                        }, finalReflections, workingObservations, runtime.config.reflectionThresholdTokens, (pass, maxPasses) => emitProgressLine(emitProgress, `Pruner pass ${pass}/${maxPasses} started.`));
-                        finalObservations = prunerResult.observations;
-                        debugLog("compaction.pruner.result", {
-                            stopReason: prunerResult.stopReason,
-                            fellBack: prunerResult.fellBack,
-                            droppedIds: prunerResult.droppedIds,
-                            passes: prunerResult.passes,
-                            beforeObservations: workingObservations.length,
-                            afterObservations: finalObservations.length,
-                        });
                         if (hasUI) {
-                            ui?.notify(`Observational memory: diagnostics — ${formatReflectorStats(reflectorResult.stats)}; coverage ${formatCoverageCounts(coverageBefore)} → ${formatCoverageCounts(coverageAfter)}; ${formatPrunerStats(prunerResult)}`, "info");
-                        }
-                        if (prunerResult.fellBack && hasUI) {
-                            ui?.notify("Observational memory: pruner run failed; kept observation set unchanged", "warning");
+                            ui?.notify(`Observational memory: reflector — ${formatReflectorStats(reflectorResult.stats)}; coverage ${formatCoverageCounts(coverageBefore)} → ${formatCoverageCounts(coverageAfter)}`, "info");
                         }
                     }
                     catch (error) {
                         const msg = error instanceof Error ? error.message : String(error);
-                        debugLog("compaction.reflect_prune.error", { errorMessage: msg });
+                        debugLog("compaction.reflector.error", { errorMessage: msg });
                         if (hasUI)
-                            ui?.notify(`Observational memory: reflect/prune failed: ${msg}`, "warning");
+                            ui?.notify(`Observational memory: reflector failed: ${msg}`, "warning");
                     }
                 }
+                // ================================================================
+                // DETERMINISTIC PRUNER: sort-based dropping instead of LLM agent.
+                // Same logic as the LLM pruner (coverage → relevance → age)
+                // but zero-cost and deterministic.
+                // ================================================================
+                const prunerResult = deterministicPrune(finalObservations, finalReflections, runtime.config.reflectionThresholdTokens);
+                finalObservations = prunerResult.observations;
+                debugLog("compaction.pruner.result", {
+                    fellBack: prunerResult.fellBack,
+                    droppedIds: prunerResult.droppedIds,
+                    tokensBefore: prunerResult.tokensBefore,
+                    tokensAfter: prunerResult.tokensAfter,
+                    beforeObservations: workingObservations.length,
+                    afterObservations: finalObservations.length,
+                });
+                emitProgressLine(emitProgress, `Deterministic pruner dropped ${prunerResult.droppedIds.length} observation${prunerResult.droppedIds.length === 1 ? "" : "s"} (~${prunerResult.tokensBefore.toLocaleString()} → ~${prunerResult.tokensAfter.toLocaleString()} tokens).`);
+                if (prunerResult.fellBack && hasUI) {
+                    ui?.notify("Observational memory: pruner could not reach budget (too many protected observations)", "warning");
+                }
+                // ================================================================
+                // BUILD FINAL SUMMARY: narrative (from unified call) +
+                // observations/reflections markdown (from renderSummary).
+                // This gives the LLM BOTH narrative context AND factual memory.
+                // ================================================================
                 emitProgressLine(emitProgress, `Rendering final memory summary from ${finalObservations.length} observations and ${finalReflections.length} reflections…`);
-                const summary = renderSummary(finalReflections, finalObservations);
+                const memoryMarkdown = renderSummary(finalReflections, finalObservations);
+                // Combine: narrative summary first (what happened), then memory
+                // (what was learned). Previous compaction's narrative is already
+                // merged into the unified call's output via previousSummary.
+                const summary = unifiedNarrativeSummary
+                    ? `${unifiedNarrativeSummary}\n\n---\n\n${memoryMarkdown}`
+                    : memoryMarkdown;
                 if (finalObservations.length === 0) {
                     throw new Error("invariant violated: finalObservations empty after delta guard");
                 }
@@ -341,6 +366,7 @@ export function registerCompactionHook(ext, runtime) {
                     finalReflections: finalReflections.length,
                     firstKeptEntryId,
                     tokensBefore,
+                    hasNarrative: !!unifiedNarrativeSummary,
                 });
                 emitProgressLine(emitProgress, `Compaction assembled — ${finalObservations.length} observation${finalObservations.length === 1 ? "" : "s"}, ${finalReflections.length} reflection${finalReflections.length === 1 ? "" : "s"}.`);
                 if (hasUI)
@@ -364,10 +390,10 @@ export function registerCompactionHook(ext, runtime) {
     function persistProjectObservations(ctx, reflections) {
         const store = getProjectObsStore();
         if (!store)
-            return; // Not available in standalone spectral mode.
+            return;
         const projectId = store.getProjectByCwd(ctx.cwd);
         if (!projectId)
-            return; // No project registered for this cwd.
+            return;
         const sessionId = ctx.sessionManager.getSessionId?.();
         if (!sessionId)
             return;

package/dist/memory/prompts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/memory/prompts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,+QAA+Q,CAAC;AAE1S,eAAO,MAAM,yBAAyB,6oHAmD+F,CAAC;AAEtI,eAAO,MAAM,0BAA0B,67CAkB+F,CAAC;AAEvI,eAAO,MAAM,gBAAgB,8+CAasI,CAAC;AAEpK,eAAO,MAAM,eAAe,knTAoC2G,CAAC;AAExI,eAAO,MAAM,gBAAgB,69UA0DwH,CAAC;AAEtJ,eAAO,MAAM,aAAa,u2cAgFuP,CAAC;AASlR,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGlF;AASD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/E;AAED,eAAO,MAAM,0BAA0B,07BAOoS,CAAC"}
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../../src/memory/prompts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,+QAA+Q,CAAC;AAE1S,eAAO,MAAM,yBAAyB,6oHAmD+F,CAAC;AAEtI,eAAO,MAAM,0BAA0B,67CAkB+F,CAAC;AAEvI,eAAO,MAAM,gBAAgB,8+CAasI,CAAC;AAEpK,eAAO,MAAM,eAAe,knTAoC2G,CAAC;AAExI,eAAO,MAAM,gBAAgB,69UA0DwH,CAAC;AAEtJ,eAAO,MAAM,aAAa,u2cAgFuP,CAAC;AAiBlR,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIlF;AASD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAG/E;AAED,eAAO,MAAM,0BAA0B,07BAOoS,CAAC"}

package/dist/memory/prompts.js

@@ -261,11 +261,20 @@ What you CANNOT do:
 It is valid to end a pass with zero drops if the pool genuinely has nothing more to cut — a follow-up pass will be skipped when a run returns zero drops. On late pressure passes, first re-check old [coverage: reinforced] and [coverage: cited] observations as active-memory redundancies before deciding there are no sound drops. Do not force drops you don't believe in.
 
 Remember: pruning is active-memory management, not source deletion. A drop that looks reasonable at "low" still becomes a mistake if the content was a user correction with a mis-labeled relevance and no reflection captures it with equivalent fidelity. Read before you cut.`;
+const REFLECTOR_UNIFIED_PASS = `Pass strategy — combined broad synthesis + atomic facts in a single pass.
+
+Phase 1 — Multi-observation synthesis: First crystallize broad durable patterns, repeated preferences, recurring constraints, stable work style, and project-level themes supported by multiple observations. Every reflection in this phase must cite at least 2 distinct supportingObservationIds whose durable meaning is captured by the reflection. If an existing reflection already captures the pattern, repeat the exact same content when adding support ids materially improves active-memory coverage.
+
+Phase 2 — Atomic durable facts + safety review: Then capture important durable facts that may be supported by a single authoritative observation: explicit user preferences, hard constraints, corrections, decisions, completed milestones, project facts, release or rollback caveats, important technical context, and other load-bearing facts future agents must not forget. Review high and critical observations against reflections created in phase 1, and catch durable information still missing. Strengthen existing or newly-created reflections by repeating exact reflection content with additional supportingObservationIds for high, critical, and old medium observations whose durable meaning is already captured by that reflection.
+
+Do not duplicate earlier reflections; repeat exact existing content only to add missing support or promote no-provenance legacy memory. Create new reflections only when durable meaning is still missing. Do not create low-quality reflections just for coverage, and do not attach observations whose unique exact detail or current task state is not captured with equivalent fidelity.`;
 const REFLECTOR_PASS_STRATEGIES = {
     1: `Pass strategy — multi-observation synthesis. Find broad durable patterns, repeated preferences, recurring constraints, stable work style, and project-level themes supported by multiple observations. Every reflection recorded in this pass must cite at least 2 distinct supportingObservationIds whose durable meaning is captured by the reflection. Do not create one-off event summaries; leave important single-observation facts, safety review, and coverage strengthening for the final reflector pass. If an existing reflection already captures the pattern, repeat the exact same content when adding support ids materially improves active-memory coverage.`,
     2: `Pass strategy — final atomic durable facts, safety review, and coverage strengthening. Capture important durable facts that may be supported by a single authoritative observation: explicit user preferences, hard constraints, corrections, decisions, completed milestones, project facts, release or rollback caveats, important technical context, and other load-bearing facts future agents must not forget. Review high and critical observations against current reflections, including reflections created in pass 1, and catch durable information still missing. Strengthen existing or newly-created reflections by repeating exact reflection content with additional supportingObservationIds for high, critical, and old medium observations whose durable meaning is already captured by that reflection. Do not duplicate earlier reflections; repeat exact existing content only to add missing support or promote no-provenance legacy memory. Create new reflections only when durable meaning is still missing. Do not create low-quality reflections just for coverage, and do not attach observations whose unique exact detail or current task state is not captured with equivalent fidelity.`,
 };
 export function buildReflectorPassGuidance(pass, maxPasses) {
+    if (maxPasses === 1)
+        return REFLECTOR_UNIFIED_PASS;
     const tier = Math.min(2, Math.max(1, pass));
     return `Pass ${pass} of up to ${maxPasses}. ${REFLECTOR_PASS_STRATEGIES[tier]}`;
 }

package/dist/memory/unified-compaction.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Unified Compaction — single LLM call replacing both:
+ *   1. Core spectral generateSummary() (narrative conversation summary)
+ *   2. Sync catch-up observer (observation extraction from gap entries)
+ *
+ * Uses a text-based delimited output format (compatible with any model
+ * without requiring native structured-output support):
+ *
+ *   ===NARRATIVE===
+ *   ## Goal
+ *   ...
+ *
+ *   ===OBSERVATIONS===
+ *   [YYYY-MM-DD HH:MM] [relevance] Content line
+ *   ...
+ */
+import type { AgentMessage, ThinkingLevel } from "../sdk/agent-core/index.js";
+import type { Model } from "../sdk/ai/index.js";
+import type { ObservationRecord } from "./types.js";
+export interface UnifiedCompactionInput {
+    /** Messages to summarize (from core compaction preparation) */
+    messagesToSummarize: AgentMessage[];
+    /** Serialized gap entries as text with source entry labels */
+    gapChunk?: string;
+    /** Source entry IDs from gap entries */
+    gapSourceEntryIds?: string[];
+    /** Model to use */
+    model: Model<any>;
+    /** API key */
+    apiKey: string;
+    /** Request headers */
+    headers?: Record<string, string>;
+    /** Abort signal */
+    signal?: AbortSignal;
+    /** Previous compaction summary for iterative update */
+    previousSummary?: string;
+    /** Custom instructions for summarization focus */
+    customInstructions?: string;
+    /** Thinking level for reasoning models */
+    thinkingLevel?: ThinkingLevel;
+    /** Reserve tokens for prompt + output */
+    reserveTokens: number;
+}
+export interface UnifiedCompactionOutput {
+    /** Markdown narrative summary (for CompactionEntry.summary) */
+    narrativeSummary: string;
+    /** Observations extracted from the conversation */
+    observations: ObservationRecord[];
+    /** Files read */
+    readFiles: string[];
+    /** Files modified */
+    modifiedFiles: string[];
+}
+/**
+ * Generate a unified compaction result: narrative summary + observations
+ * in a single LLM call. Uses delimited text output for broad model compatibility.
+ */
+export declare function generateUnifiedCompaction(input: UnifiedCompactionInput): Promise<UnifiedCompactionOutput>;
+//# sourceMappingURL=unified-compaction.d.ts.map

package/dist/memory/unified-compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-compaction.d.ts","sourceRoot":"","sources":["../../src/memory/unified-compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAC9E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAUhD,OAAO,KAAK,EAAE,iBAAiB,EAAa,MAAM,YAAY,CAAC;AAkO/D,MAAM,WAAW,sBAAsB;IACtC,+DAA+D;IAC/D,mBAAmB,EAAE,YAAY,EAAE,CAAC;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,mBAAmB;IACnB,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC;IAClB,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mBAAmB;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,uDAAuD;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0CAA0C;IAC1C,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,yCAAyC;IACzC,aAAa,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACvC,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,iBAAiB;IACjB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,qBAAqB;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAC9C,KAAK,EAAE,sBAAsB,GAC3B,OAAO,CAAC,uBAAuB,CAAC,CA0IlC"}

package/dist/memory/unified-compaction.js

@@ -0,0 +1,332 @@
+/**
+ * Unified Compaction — single LLM call replacing both:
+ *   1. Core spectral generateSummary() (narrative conversation summary)
+ *   2. Sync catch-up observer (observation extraction from gap entries)
+ *
+ * Uses a text-based delimited output format (compatible with any model
+ * without requiring native structured-output support):
+ *
+ *   ===NARRATIVE===
+ *   ## Goal
+ *   ...
+ *
+ *   ===OBSERVATIONS===
+ *   [YYYY-MM-DD HH:MM] [relevance] Content line
+ *   ...
+ */
+import { completeSimple } from "../sdk/ai/index.js";
+import { extractFileOpsFromMessage, computeFileLists, createFileOps, formatFileOperations, } from "../sdk/coding-agent/core/compaction/utils.js";
+import { hashId } from "./ids.js";
+import { nowTimestamp, truncateRecordContent } from "./serialize.js";
+import { debugLog } from "./debug-log.js";
+// ============================================================================
+// Section Delimiters
+// ============================================================================
+const NARRATIVE_SECTION = "===NARRATIVE===";
+const OBSERVATIONS_SECTION = "===OBSERVATIONS===";
+// ============================================================================
+// Prompt Templates
+// ============================================================================
+const UNIFIED_SYSTEM_PROMPT = `You are a context compression agent. Your task has TWO complementary outputs that MUST be produced together in a single response.
+
+TASK A — NARRATIVE SUMMARY: Create a structured checkpoint of the conversation progress. This is what another LLM reads to understand where the work stands.
+
+TASK B — FACTUAL MEMORY: Extract timestamped observations (single-line facts with relevance tags). These records are the assistant's ONLY memory of this conversation after the raw messages fall out of context.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured result using the EXACT format specified.`;
+function buildUnifiedPrompt(conversationText, previousSummary, customInstructions, currentTime) {
+    let prompt = `<conversation>\n${conversationText}\n</conversation>\n\n`;
+    if (previousSummary) {
+        prompt += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
+    }
+    prompt += `Current local time: ${currentTime}\n\n`;
+    prompt += `Output your response in TWO sections delimited by the exact markers shown below.
+
+SECTION A — ${NARRATIVE_SECTION}
+
+Produce a structured context checkpoint summary using this EXACT format:
+
+## Goal
+[What is the user trying to accomplish? Can be multiple items. If updating a previous summary, preserve existing goals and add new ones.]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned by user]
+- [Or "(none)" if none were mentioned]
+[When updating: preserve existing constraints, add new ones.]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes. Preserve previously completed items, add newly completed ones.]
+
+### In Progress
+- [ ] [Current work. Update based on progress.]
+
+### Blocked
+- [Issues preventing progress, if any. Remove blockers that have been resolved.]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+[Preserve all previous decisions, add new ones.]
+
+## Next Steps
+1. [Ordered list of what should happen next. Update based on current state.]
+
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.
+${customInstructions ? `\nAdditional focus for the narrative: ${customInstructions}` : ""}
+
+SECTION B — ${OBSERVATIONS_SECTION}
+
+Extract NEW timestamped facts from the conversation. Each observation must be on its own line in this exact format:
+
+[YYYY-MM-DD HH:MM] [relevance] Single-line plain prose fact. No markdown, no bullets.
+
+Do NOT restate facts already captured in the <previous-summary>. Skip routine, low-information events (tool-call acks, status updates).
+
+OBSERVATION CONTENT RULES:
+- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.
+- Preserve user assertions exactly. When the user STATES something about themselves, their project, or their environment, capture it as an assertion. When the user ASKS something, capture it as a question.
+- Use precise action verbs (completed, resolved, implemented, chose, configured etc.).
+- Mark concrete completions explicitly: "completed: implemented X at path/to/file.ts; user confirmed tests pass."
+- Split compound statements into separate observations (one fact per line).
+- Group repeated similar tool calls into a single observation.
+- Preserve exact file paths, function names, line numbers, error messages (verbatim), package names, identifiers.
+- Use the timestamp from the closest conversation message. Fall back to the current local time if no message timestamp applies.
+
+RELEVANCE LEVELS (pick one per observation):
+- critical: user identity, role, persistent preferences, explicit corrections, concrete completions that future runs MUST NOT redo.
+- high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints.
+- medium: task-level context that helps within the current work. Default when unsure between medium and high.
+- low: routine tool-call acks, repetitive status updates, trivially re-derivable content. Skip these unless they carry unique detail.
+
+Do NOT default everything to "high" or "critical". Most observations should be "medium". Use "low" only for truly routine items.
+
+Focus areas for observations:
+- User identity, preferences, constraints, corrections.
+- Project goals, architectural decisions, rationale.
+- File paths and line numbers of changes.
+- Error messages (verbatim).
+- Completed work that should not be redone.
+- Named identifiers (package names, function/variable names, ticket IDs, commit SHAs).`;
+    return prompt;
+}
+// ============================================================================
+// Conversation Serialization
+// ============================================================================
+const TOOL_RESULT_MAX_CHARS = 2000;
+const VISION_DESCRIPTION_PREFIX = "[Image description from ";
+function stripVisionBlocks(text) {
+    if (!text.includes(VISION_DESCRIPTION_PREFIX))
+        return text;
+    const lines = text.split("\n");
+    const kept = [];
+    let skipping = false;
+    for (const line of lines) {
+        if (!skipping && line.startsWith(VISION_DESCRIPTION_PREFIX)) {
+            skipping = true;
+            continue;
+        }
+        if (skipping) {
+            if (line === "]") {
+                skipping = false;
+            }
+            continue;
+        }
+        kept.push(line);
+    }
+    return kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+function serializeMessagesForUnified(messages) {
+    const parts = [];
+    for (const msg of messages) {
+        if (msg.role === "user") {
+            const content = typeof msg.content === "string"
+                ? msg.content
+                : Array.isArray(msg.content)
+                    ? msg.content.filter((c) => c.type === "text").map(c => c.text).join("")
+                    : "";
+            const cleaned = stripVisionBlocks(content);
+            if (cleaned)
+                parts.push(`[User]: ${cleaned}`);
+        }
+        else if (msg.role === "assistant" && "content" in msg && Array.isArray(msg.content)) {
+            const textParts = [];
+            const toolParts = [];
+            for (const block of msg.content) {
+                if (block.type === "text" && "text" in block) {
+                    textParts.push(block.text);
+                }
+                else if (block.type === "toolCall" && "name" in block) {
+                    const args = block.arguments;
+                    const argsStr = Object.keys(args).sort().map(k => `${k}=${JSON.stringify(args[k])}`).join(", ");
+                    toolParts.push(`${block.name}(${argsStr})`);
+                }
+            }
+            const combined = [...textParts, ...(toolParts.length ? [`[Tools: ${toolParts.join("; ")}]`] : [])];
+            if (combined.length)
+                parts.push(`[Assistant]: ${combined.join("\n")}`);
+        }
+        else if (msg.role === "toolResult") {
+            const text = Array.isArray(msg.content)
+                ? msg.content.filter((c) => c.type === "text").map(c => c.text).join("")
+                : typeof msg.content === "string" ? msg.content : "";
+            if (text) {
+                const truncated = text.length > TOOL_RESULT_MAX_CHARS
+                    ? `${text.slice(0, TOOL_RESULT_MAX_CHARS)}\n[...truncated]`
+                    : text;
+                parts.push(`[Tool result]: ${truncated}`);
+            }
+        }
+        else if (msg.role === "compactionSummary" && "summary" in msg) {
+            parts.push(`[Previous compaction summary]: ${msg.summary}`);
+        }
+    }
+    return parts.join("\n\n");
+}
+// ============================================================================
+// Output Parsing
+// ============================================================================
+const OBSERVATION_LINE_RE = /^\[(\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2})\]\s*\[(low|medium|high|critical)\]\s*(.+)$/i;
+function parseObservations(text) {
+    const results = [];
+    const lines = text.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#") || trimmed === OBSERVATIONS_SECTION)
+            continue;
+        const match = trimmed.match(OBSERVATION_LINE_RE);
+        if (match) {
+            results.push({
+                timestamp: match[1],
+                relevance: match[2].toLowerCase(),
+                content: match[3].trim(),
+            });
+        }
+    }
+    return results;
+}
+function normalizeObservation(raw) {
+    const content = truncateRecordContent(raw.content);
+    if (!content)
+        return undefined;
+    const validRelevance = ["low", "medium", "high", "critical"];
+    const relevance = validRelevance.includes(raw.relevance)
+        ? raw.relevance
+        : "medium";
+    return {
+        id: hashId(content),
+        content,
+        timestamp: raw.timestamp,
+        relevance,
+    };
+}
+/**
+ * Generate a unified compaction result: narrative summary + observations
+ * in a single LLM call. Uses delimited text output for broad model compatibility.
+ */
+export async function generateUnifiedCompaction(input) {
+    const { messagesToSummarize, gapChunk, model, apiKey, headers, signal, previousSummary, customInstructions, thinkingLevel, reserveTokens, } = input;
+    const maxTokens = Math.min(Math.floor(0.8 * reserveTokens), model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
+    // Build conversation text
+    const parts = [];
+    const coreText = serializeMessagesForUnified(messagesToSummarize);
+    if (coreText)
+        parts.push(coreText);
+    if (gapChunk?.trim()) {
+        parts.push(`\n--- Gap entries (unobserved raw conversation) ---\n${gapChunk}`);
+    }
+    const conversationText = parts.join("\n\n");
+    const currentTime = nowTimestamp();
+    const userPrompt = buildUnifiedPrompt(conversationText, previousSummary, customInstructions, currentTime);
+    const promptMessages = [
+        {
+            role: "user",
+            content: [{ type: "text", text: userPrompt }],
+            timestamp: Date.now(),
+        },
+    ];
+    const options = { maxTokens, signal, apiKey, headers };
+    if (model.reasoning && thinkingLevel && thinkingLevel !== "off") {
+        options.reasoning = thinkingLevel;
+    }
+    debugLog("unified_compaction.start", {
+        messageCount: messagesToSummarize.length,
+        hasGap: !!gapChunk?.trim(),
+        conversationLength: conversationText.length,
+    });
+    const response = await completeSimple(model, { systemPrompt: UNIFIED_SYSTEM_PROMPT, messages: promptMessages }, options);
+    if (response.stopReason === "error") {
+        throw new Error(`Unified compaction failed: ${response.errorMessage || "Unknown error"}`);
+    }
+    if (response.stopReason === "aborted") {
+        throw new Error("Unified compaction aborted");
+    }
+    const fullText = response.content
+        .filter((c) => c.type === "text")
+        .map((c) => c.text)
+        .join("\n");
+    // Parse the two sections
+    const narrativeIdx = fullText.indexOf(NARRATIVE_SECTION);
+    const obsIdx = fullText.indexOf(OBSERVATIONS_SECTION);
+    let narrativeSummary;
+    let rawObservationsText;
+    if (narrativeIdx >= 0 && obsIdx >= 0) {
+        // Both sections present
+        if (narrativeIdx < obsIdx) {
+            narrativeSummary = fullText.slice(narrativeIdx + NARRATIVE_SECTION.length, obsIdx).trim();
+        }
+        else {
+            narrativeSummary = fullText.slice(narrativeIdx + NARRATIVE_SECTION.length).trim();
+        }
+        rawObservationsText = fullText.slice(obsIdx + OBSERVATIONS_SECTION.length).trim();
+    }
+    else if (narrativeIdx >= 0) {
+        // Only narrative
+        narrativeSummary = fullText.slice(narrativeIdx + NARRATIVE_SECTION.length).trim();
+        rawObservationsText = "";
+    }
+    else if (obsIdx >= 0) {
+        // Only observations (unusual but handle gracefully)
+        narrativeSummary = fullText.slice(0, obsIdx).trim();
+        rawObservationsText = fullText.slice(obsIdx + OBSERVATIONS_SECTION.length).trim();
+    }
+    else {
+        // No delimiters found — treat entire output as narrative
+        debugLog("unified_compaction.no_delimiters", { textLength: fullText.length });
+        narrativeSummary = fullText;
+        rawObservationsText = "";
+    }
+    // Parse observations
+    const rawObservations = parseObservations(rawObservationsText);
+    const observations = [];
+    const seen = new Set();
+    for (const raw of rawObservations) {
+        const normalized = normalizeObservation(raw);
+        if (normalized && !seen.has(normalized.id)) {
+            seen.add(normalized.id);
+            observations.push(normalized);
+        }
+    }
+    // Compute file operations
+    const fileOps = createFileOps();
+    for (const msg of messagesToSummarize) {
+        extractFileOpsFromMessage(msg, fileOps);
+    }
+    const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+    // Append file operations to narrative
+    const fullNarrativeSummary = narrativeSummary + formatFileOperations(readFiles, modifiedFiles);
+    debugLog("unified_compaction.result", {
+        narrativeLength: fullNarrativeSummary.length,
+        observationCount: observations.length,
+        rawObservationLines: rawObservations.length,
+    });
+    return {
+        narrativeSummary: fullNarrativeSummary,
+        observations,
+        readFiles,
+        modifiedFiles,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.16",
+  "version": "0.9.17",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,